This is /home/cyd/emacs/doc/emacs/../../info/emacs, produced by
makeinfo version 4.13 from /home/cyd/emacs/doc/emacs/emacs.texi.

This is the `GNU Emacs Manual', updated for Emacs version 24.2.

Copyright (C) 1985-1987, 1993-2012 Free Software Foundation, Inc.

     Permission is granted to copy, distribute and/or modify this
     document under the terms of the GNU Free Documentation License,
     Version 1.3 or any later version published by the Free Software
     Foundation; with the Invariant Sections being "The GNU Manifesto,"
     "Distribution" and "GNU GENERAL PUBLIC LICENSE," with the
     Front-Cover texts being "A GNU Manual," and with the Back-Cover
     Texts as in (a) below.  A copy of the license is included in the
     section entitled "GNU Free Documentation License."

     (a) The FSF's Back-Cover Text is: "You have the freedom to copy and
     modify this GNU manual.  Buying copies from the FSF supports it in
     developing GNU and promoting software freedom."

INFO-DIR-SECTION Emacs
START-INFO-DIR-ENTRY
* Emacs: (emacs).       The extensible self-documenting text editor.
END-INFO-DIR-ENTRY


File: emacs,  Node: Stack Buffer,  Next: Other GDB Buffers,  Prev: Threads Buffer,  Up: GDB Graphical Interface

27.6.5.5 Stack Buffer
.....................

The GDB Stack buffer displays a "call stack", with one line for each of
the nested subroutine calls ("stack frames") in the debugger session.
*Note Backtraces: (gdb)Backtrace.

   On graphical displays, the selected stack frame is indicated by an
arrow in the fringe.  On text terminals, or when fringes are disabled,
the selected stack frame is displayed in reverse contrast.  To select a
stack frame, move point in its line and type <RET>
(`gdb-frames-select'), or click `Mouse-2' on it.  Doing so also updates
the Locals buffer (*note Other GDB Buffers::).


File: emacs,  Node: Other GDB Buffers,  Next: Watch Expressions,  Prev: Stack Buffer,  Up: GDB Graphical Interface

27.6.5.6 Other GDB Buffers
..........................

Locals Buffer
     This buffer displays the values of local variables of the current
     frame for simple data types (*note Frame Info: (gdb)Frame Info.).
     Press <RET> or click `Mouse-2' on the value if you want to edit it.

     Arrays and structures display their type only.  With GDB 6.4 or
     later, you can examine the value of the local variable at point by
     typing <RET>, or with a `Mouse-2' click.  With earlier versions of
     GDB, use <RET> or `Mouse-2' on the type description
     (`[struct/union]' or `[array]').  *Note Watch Expressions::.

Registers Buffer
     This buffer displays the values held by the registers (*note
     Registers: (gdb)Registers.).  Press <RET> or click `Mouse-2' on a
     register if you want to edit its value.  With GDB 6.4 or later,
     recently changed register values display with
     `font-lock-warning-face'.

Assembler Buffer
     The assembler buffer displays the current frame as machine code.
     An arrow points to the current instruction, and you can set and
     remove breakpoints as in a source buffer.  Breakpoint icons also
     appear in the fringe or margin.

Memory Buffer
     The memory buffer lets you examine sections of program memory
     (*note Memory: (gdb)Memory.).  Click `Mouse-1' on the appropriate
     part of the header line to change the starting address or number
     of data items that the buffer displays.  Alternatively, use `S' or
     `N' respectively.  Click `Mouse-3' on the header line to select
     the display format or unit size for these data items.

   When `gdb-many-windows' is non-`nil', the locals buffer shares its
window with the registers buffer, just like breakpoints and threads
buffers. To switch from one to the other, click with `Mouse-1' on the
relevant button in the header line.


File: emacs,  Node: Watch Expressions,  Next: Multithreaded Debugging,  Prev: Other GDB Buffers,  Up: GDB Graphical Interface

27.6.5.7 Watch Expressions
..........................

If you want to see how a variable changes each time your program stops,
move point into the variable name and click on the watch icon in the
tool bar (`gud-watch') or type `C-x C-a C-w'.  If you specify a prefix
argument, you can enter the variable name in the minibuffer.

   Each watch expression is displayed in the speedbar (*note
Speedbar::).  Complex data types, such as arrays, structures and unions
are represented in a tree format.  Leaves and simple data types show
the name of the expression and its value and, when the speedbar frame
is selected, display the type as a tooltip.  Higher levels show the
name, type and address value for pointers and just the name and type
otherwise.  Root expressions also display the frame address as a
tooltip to help identify the frame in which they were defined.

   To expand or contract a complex data type, click `Mouse-2' or press
<SPC> on the tag to the left of the expression.  Emacs asks for
confirmation before expanding the expression if its number of immediate
children exceeds the value of the variable `gdb-max-children'.

   To delete a complex watch expression, move point to the root
expression in the speedbar and type `D' (`gdb-var-delete').

   To edit a variable with a simple data type, or a simple element of a
complex data type, move point there in the speedbar and type <RET>
(`gdb-edit-value').  Or you can click `Mouse-2' on a value to edit it.
Either way, this reads the new value using the minibuffer.

   If you set the variable `gdb-show-changed-values' to non-`nil' (the
default value), Emacs uses `font-lock-warning-face' to highlight values
that have recently changed and `shadow' face to make variables which
have gone out of scope less noticeable.  When a variable goes out of
scope you can't edit its value.

   If the variable `gdb-delete-out-of-scope' is non-`nil' (the default
value), Emacs automatically deletes watch expressions which go out of
scope.  Sometimes, when re-entering the same function, it may be useful
to set this value to `nil' so that you don't need to recreate the watch
expression.

   If the variable `gdb-use-colon-colon-notation' is non-`nil', Emacs
uses the `FUNCTION::VARIABLE' format.  This allows the user to display
watch expressions which share the same variable name.  The default
value is `nil'.

   To automatically raise the speedbar every time the display of watch
expressions updates, set `gdb-speedbar-auto-raise' to non-`nil'.  This
can be useful if you are debugging with a full screen Emacs frame.


File: emacs,  Node: Multithreaded Debugging,  Prev: Watch Expressions,  Up: GDB Graphical Interface

27.6.5.8 Multithreaded Debugging
................................

In GDB's "all-stop mode", whenever your program stops, all execution
threads stop.  Likewise, whenever you restart the program, all threads
start executing.  *Note All-Stop Mode: (gdb)All-Stop Mode.  For some
multi-threaded targets, GDB supports a further mode of operation,
called "non-stop mode", in which you can examine stopped program
threads in the debugger while other threads continue to execute freely.
*Note Non-Stop Mode: (gdb)Non-Stop Mode.  Versions of GDB prior to 7.0
do not support non-stop mode, and it does not work on all targets.

   The variable `gdb-non-stop-setting' determines whether Emacs runs
GDB in all-stop mode or non-stop mode.  The default is `t', which means
it tries to use non-stop mode if that is available.  If you change the
value to `nil', or if non-stop mode is unavailable, Emacs runs GDB in
all-stop mode.  The variable takes effect when Emacs begins a debugging
session; if you change its value, you should restart any active
debugging session.

   When a thread stops in non-stop mode, Emacs usually switches to that
thread.  If you don't want Emacs to do this switch if another stopped
thread is already selected, change the variable
`gdb-switch-when-another-stopped' to `nil'.

   Emacs can decide whether or not to switch to the stopped thread
depending on the reason which caused the stop.  Customize the variable
`gdb-switch-reasons' to select the stop reasons which will cause a
thread switch.

   The variable `gdb-stopped-hooks' allows you to execute your
functions whenever some thread stops.

   In non-stop mode, you can switch between different modes for GUD
execution control commands.

"Non-stop/A"
     When `gdb-gud-control-all-threads' is `t' (the default value),
     interruption and continuation commands apply to all threads, so
     you can halt or continue all your threads with one command using
     `gud-stop-subjob' and `gud-cont', respectively.  The `Go' button
     is shown on the toolbar when at least one thread is stopped,
     whereas `Stop' button is shown when at least one thread is running.

"Non-stop/T"
     When `gdb-gud-control-all-threads' is `nil', only the current
     thread is stopped/continued.  `Go' and `Stop' buttons on the GUD
     toolbar are shown depending on the state of current thread.

   You can change the current value of `gdb-gud-control-all-threads'
from the tool bar or from `GUD->GDB-MI' menu.

   Stepping commands always apply to the current thread.

   In non-stop mode, you can interrupt/continue your threads without
selecting them.  Hitting `i' in threads buffer interrupts thread under
point, `c' continues it, `s' steps through.  More such commands may be
added in the future.

   Note that when you interrupt a thread, it stops with the `signal
received' reason.  If that reason is included in your
`gdb-switch-reasons' (it is by default), Emacs will switch to that
thread.


File: emacs,  Node: Executing Lisp,  Next: Lisp Libraries,  Prev: Debuggers,  Up: Building

27.7 Executing Lisp Expressions
===============================

Emacs has major modes for several variants of Lisp.  They use the same
editing commands as other programming language modes (*note
Programs::).  In addition, they provide special commands for executing
Lisp expressions.

Emacs Lisp mode
     The mode for editing Emacs Lisp source files.  It defines `C-M-x'
     to evaluate the current top-level Lisp expression.  *Note Lisp
     Eval::.

Lisp Interaction mode
     The mode for an interactive Emacs Lisp session.  It defines `C-j'
     to evaluate the expression before point and insert its value in the
     buffer.  *Note Lisp Interaction::.

Lisp mode
     The mode for editing source files of programs that run in Lisps
     other than Emacs Lisp.  It defines `C-M-x' to evaluate the current
     top-level expression in an external Lisp.  *Note External Lisp::.

Inferior Lisp mode
     The mode for an interactive session with an external Lisp which is
     being run as a subprocess (or "inferior process") of Emacs.  *Note
     External Lisp::.

Scheme mode
     Like Lisp mode, but for Scheme programs.

Inferior Scheme mode
     Like Inferior Lisp mode, but for Scheme.


File: emacs,  Node: Lisp Libraries,  Next: Lisp Eval,  Prev: Executing Lisp,  Up: Building

27.8 Libraries of Lisp Code for Emacs
=====================================

Emacs Lisp code is stored in files whose names conventionally end in
`.el'.  Such files are automatically visited in Emacs Lisp mode.

   Emacs Lisp code can be compiled into byte-code, which loads faster,
takes up less space, and executes faster.  By convention, compiled
Emacs Lisp code goes in a separate file whose name ends in `.elc'.  For
example, the compiled code for `foo.el' goes in `foo.elc'.  *Note Byte
Compilation: (elisp)Byte Compilation.

   To "load" an Emacs Lisp file, type `M-x load-file'.  This command
reads a file name using the minibuffer, and executes the contents of
that file as Emacs Lisp code.  It is not necessary to visit the file
first; this command reads the file directly from disk, not from an
existing Emacs buffer.

   If an Emacs Lisp file is installed in the Emacs Lisp "load path"
(defined below), you can load it by typing `M-x load-library', instead
of using `M-x load-file'.  The `M-x load-library' command prompts for a
"library name" rather than a file name; it searches through each
directory in the Emacs Lisp load path, trying to find a file matching
that library name.  If the library name is `FOO', it tries looking for
files named `FOO.elc', `FOO.el', and lastly just `FOO'; the first one
found is loaded.  This command prefers `.elc' files over `.el' files
because compiled files load and run faster.  If it finds that `LIB.el'
is newer than `LIB.elc', it issues a warning, in case someone made
changes to the `.el' file and forgot to recompile it, but loads the
`.elc' file anyway.  (Due to this behavior, you can save unfinished
edits to Emacs Lisp source files, and not recompile until your changes
are ready for use.)

   Emacs Lisp programs usually load Emacs Lisp files using the `load'
function.  This is similar to `load-library', but is lower-level and
accepts additional arguments.  *Note How Programs Do Loading:
(elisp)How Programs Do Loading.

   The Emacs Lisp load path is specified by the variable `load-path'.
Its value should be a list of directory names (strings).  These
directories are searched, in the specified order, by the `M-x
load-library' command, the lower-level `load' function, and other Emacs
functions that find Emacs Lisp libraries.  A list entry in `load-path'
can also have the special value `nil', which stands for the current
default directory, but it is almost always a bad idea to use this.  (If
you find yourself wishing that `nil' were in the list, most likely what
you really want is to use `M-x load-file'.)

   The default value of `load-path' is a list of directories where the
Lisp code for Emacs itself is stored.  If you have libraries of your
own in another directory, you can add that directory to the load path.
Unlike most other variables described in this manual, `load-path'
cannot be changed via the Customize interface (*note Easy
Customization::), but you can add a directory to it by putting a line
like this in your init file (*note Init File::):

     (add-to-list 'load-path "/path/to/my/lisp/library")

   Some commands are "autoloaded": when you run them, Emacs
automatically loads the associated library first.  For instance, the
`M-x compile' command (*note Compilation::) is autoloaded; if you call
it, Emacs automatically loads the `compile' library first.  In
contrast, the command `M-x recompile' is not autoloaded, so it is
unavailable until you load the `compile' library.

   By default, Emacs refuses to load compiled Lisp files which were
compiled with XEmacs, a modified versions of Emacs--they can cause
Emacs to crash.  Set the variable `load-dangerous-libraries' to `t' if
you want to try loading them.


File: emacs,  Node: Lisp Eval,  Next: Lisp Interaction,  Prev: Lisp Libraries,  Up: Building

27.9 Evaluating Emacs Lisp Expressions
======================================

Emacs Lisp mode is the major mode for editing Emacs Lisp.  Its mode
command is `M-x emacs-lisp-mode'.

   Emacs provides several commands for evaluating Emacs Lisp
expressions.  You can use these commands in Emacs Lisp mode, to test
your Emacs Lisp code as it is being written.  For example, after
re-writing a function, you can evaluate the function definition to make
it take effect for subsequent function calls.  These commands are also
available globally, and can be used outside Emacs Lisp mode.

`M-:'
     Read a single Emacs Lisp expression in the minibuffer, evaluate it,
     and print the value in the echo area (`eval-expression').

`C-x C-e'
     Evaluate the Emacs Lisp expression before point, and print the
     value in the echo area (`eval-last-sexp').

`C-M-x' (in Emacs Lisp mode)
`M-x eval-defun'
     Evaluate the defun containing or after point, and print the value
     in the echo area (`eval-defun').

`M-x eval-region'
     Evaluate all the Emacs Lisp expressions in the region.

`M-x eval-buffer'
     Evaluate all the Emacs Lisp expressions in the buffer.

   `M-:' (`eval-expression') reads an expression using the minibuffer,
and evaluates it.  (Before evaluating the expression, the current
buffer switches back to the buffer that was current when you typed
`M-:', not the minibuffer into which you typed the expression.)

   The command `C-x C-e' (`eval-last-sexp') evaluates the Emacs Lisp
expression preceding point in the buffer, and displays the value in the
echo area.  When the result of an evaluation is an integer, you can
type `C-x C-e' a second time to display the value of the integer result
in additional formats (octal, hexadecimal, and character).

   If `M-:' or `C-x C-e' is given a prefix argument, it inserts the
value into the current buffer at point, rather than displaying it in
the echo area.  The argument's value does not matter.

   The `eval-defun' command is bound to `C-M-x' in Emacs Lisp mode.  It
evaluates the top-level Lisp expression containing or following point,
and prints the value in the echo area.  In this context, a top-level
expression is referred to as a "defun", but it need not be an actual
`defun' (function definition).  In particular, this command treats
`defvar' expressions specially.  Normally, evaluating a `defvar'
expression does nothing if the variable it defines already has a value.
But this command unconditionally resets the variable to the initial
value specified by the `defvar'; this is convenient for debugging Emacs
Lisp programs.  `defcustom' and `defface' expressions are treated
similarly.  Note that the other commands documented in this section do
not have this special feature.

   With a prefix argument, `C-M-x' instruments the function definition
for Edebug, the Emacs Lisp Debugger.  *Note Instrumenting for Edebug:
(elisp)Instrumenting.

   The command `M-x eval-region' parses the text of the region as one
or more Lisp expressions, evaluating them one by one.  `M-x
eval-buffer' is similar but evaluates the entire buffer.

   The options `eval-expression-print-level' and
`eval-expression-print-length' control the maximum depth and length of
lists to print in the result of the evaluation commands before
abbreviating them.  `eval-expression-debug-on-error' controls whether
evaluation errors invoke the debugger when these commands are used; its
default is `t'.


File: emacs,  Node: Lisp Interaction,  Next: External Lisp,  Prev: Lisp Eval,  Up: Building

27.10 Lisp Interaction Buffers
==============================

When Emacs starts up, it contains a buffer named `*scratch*', which is
provided for evaluating Emacs Lisp expressions interactively.  Its
major mode is Lisp Interaction mode.  You can also enable Lisp
Interaction mode by typing `M-x lisp-interaction-mode'.

   In the `*scratch*' buffer, and other Lisp Interaction mode buffers,
`C-j' (`eval-print-last-sexp') evaluates the Lisp expression before
point, and inserts the value at point.  Thus, as you type expressions
into the buffer followed by `C-j' after each expression, the buffer
records a transcript of the evaluated expressions and their values.
All other commands in Lisp Interaction mode are the same as in Emacs
Lisp mode.

   At startup, the `*scratch*' buffer contains a short message, in the
form of a Lisp comment, that explains what it is for.  This message is
controlled by the variable `initial-scratch-message', which should be
either a string, or `nil' (which means to suppress the message).

   An alternative way of evaluating Emacs Lisp expressions
interactively is to use Inferior Emacs Lisp mode, which provides an
interface rather like Shell mode (*note Shell Mode::) for evaluating
Emacs Lisp expressions.  Type `M-x ielm' to create an `*ielm*' buffer
which uses this mode.  For more information, see that command's
documentation.


File: emacs,  Node: External Lisp,  Prev: Lisp Interaction,  Up: Building

27.11 Running an External Lisp
==============================

Lisp mode is the major mode for editing programs written in
general-purpose Lisp dialects, such as Common Lisp.  Its mode command
is `M-x lisp-mode'.  Emacs uses Lisp mode automatically for files whose
names end in `.l', `.lsp', or `.lisp'.

   You can run an external Lisp session as a subprocess or "inferior
process" of Emacs, and pass expressions to it to be evaluated.  To
begin an external Lisp session, type `M-x run-lisp'.  This runs the
program named `lisp', and sets it up so that both input and output go
through an Emacs buffer named `*inferior-lisp*'.  To change the name of
the Lisp program run by `M-x run-lisp', change the variable
`inferior-lisp-program'.

   The major mode for the `*lisp*' buffer is Inferior Lisp mode, which
combines the characteristics of Lisp mode and Shell mode (*note Shell
Mode::).  To send input to the Lisp session, go to the end of the
`*lisp*' buffer and type the input, followed by <RET>.  Terminal output
from the Lisp session is automatically inserted in the buffer.

   When you edit a Lisp program in Lisp mode, you can type `C-M-x'
(`lisp-eval-defun') to send an expression from the Lisp mode buffer to
a Lisp session that you had started with `M-x run-lisp'.  The
expression sent is the top-level Lisp expression at or following point.
The resulting value goes as usual into the `*inferior-lisp*' buffer.
Note that the effect of `C-M-x' in Lisp mode is thus very similar to
its effect in Emacs Lisp mode (*note Lisp Eval::), except that the
expression is sent to a different Lisp environment instead of being
evaluated in Emacs.

   The facilities for editing Scheme code, and for sending expressions
to a Scheme subprocess, are very similar.  Scheme source files are
edited in Scheme mode, which can be explicitly enabled with `M-x
scheme-mode'.  You can initiate a Scheme session by typing `M-x
run-scheme' (the buffer for interacting with Scheme is named
`*scheme*'), and send expressions to it by typing `C-M-x'.


File: emacs,  Node: Maintaining,  Next: Abbrevs,  Prev: Building,  Up: Top

28 Maintaining Large Programs
*****************************

This chapter describes Emacs features for maintaining large programs.
If you are maintaining a large Lisp program, then in addition to the
features described here, you may find the `ERT' ("Emacs Lisp Regression
Testing") library useful (*note ERT: (ert)Top.).

* Menu:

* Version Control::     Using version control systems.
* Change Log::          Maintaining a change history for your program.
* Tags::                Go directly to any function in your program in one
                          command.  Tags remembers which file it is in.
* EDE::                 An integrated development environment for Emacs.

* Emerge::              A convenient way of merging two versions of a program.


File: emacs,  Node: Version Control,  Next: Change Log,  Up: Maintaining

28.1 Version Control
====================

A "version control system" is a program that can record multiple
versions of a source file, storing information such as the creation
time of each version, who made it, and a description of what was
changed.

   The Emacs version control interface is called "VC".  VC commands
work with several different version control systems; currently, it
supports GNU Arch, Bazaar, CVS, Git, Mercurial, Monotone, RCS,
SCCS/CSSC, and Subversion.  Of these, the GNU project distributes CVS,
Arch, RCS, and Bazaar.

   VC is enabled automatically whenever you visit a file governed by a
version control system.  To disable VC entirely, set the customizable
variable `vc-handled-backends' to `nil' (*note Customizing VC::).

* Menu:

* Introduction to VC::  How version control works in general.
* VC Mode Line::        How the mode line shows version control status.
* Basic VC Editing::    How to edit a file under version control.
* Log Buffer::          Features available in log entry buffers.
* Registering::         Putting a file under version control.
* Old Revisions::       Examining and comparing old versions.
* VC Change Log::       Viewing the VC Change Log.
* VC Undo::             Canceling changes before or after committing.
* VC Directory Mode::   Listing files managed by version control.
* Branches::            Multiple lines of development.

* Miscellaneous VC::    Various other commands and features of VC.
* Customizing VC::      Variables that change VC's behavior.


File: emacs,  Node: Introduction to VC,  Next: VC Mode Line,  Up: Version Control

28.1.1 Introduction to Version Control
--------------------------------------

VC allows you to use a version control system from within Emacs,
integrating the version control operations smoothly with editing.  It
provides a uniform interface for common operations in many version
control operations.

   Some uncommon or intricate version control operations, such as
altering repository settings, are not supported in VC.  You should
perform such tasks outside Emacs, e.g. via the command line.

   This section provides a general overview of version control, and
describes the version control systems that VC supports.  You can skip
this section if you are already familiar with the version control system
you want to use.

* Menu:

* Why Version Control?::    Understanding the problems it addresses.
* Version Control Systems:: Supported version control back-end systems.
* VCS Concepts::            Words and concepts related to version control.
* VCS Merging::             How file conflicts are handled.
* VCS Changesets::          How changes are grouped.
* VCS Repositories::        Where version control repositories are stored.
* Types of Log File::       The VCS log in contrast to the ChangeLog.


File: emacs,  Node: Why Version Control?,  Next: Version Control Systems,  Up: Introduction to VC

28.1.1.1 Understanding the problems it addresses
................................................

Version control systems provide you with three important capabilities:

   * "Reversibility": the ability to back up to a previous state if you
     discover that some modification you did was a mistake or a bad
     idea.

   * "Concurrency": the ability to have many people modifying the same
     collection of files knowing that conflicting modifications can be
     detected and resolved.

   * "History": the ability to attach historical data to your data,
     such as explanatory comments about the intention behind each
     change to it.  Even for a programmer working solo, change
     histories are an important aid to memory; for a multi-person
     project, they are a vitally important form of communication among
     developers.


File: emacs,  Node: Version Control Systems,  Next: VCS Concepts,  Prev: Why Version Control?,  Up: Introduction to VC

28.1.1.2 Supported Version Control Systems
..........................................

VC currently works with many different version control systems, which
it refers to as "back ends":

   * SCCS was the first version control system ever built, and was long
     ago superseded by more advanced ones.  VC compensates for certain
     features missing in SCCS (e.g. tag names for releases) by
     implementing them itself.  Other VC features, such as multiple
     branches, are simply unavailable.  Since SCCS is non-free, we
     recommend avoiding it.

   * CSSC is a free replacement for SCCS.  You should use CSSC only if,
     for some reason, you cannot use a more recent and better-designed
     version control system.

   * RCS is the free version control system around which VC was
     initially built.  It is relatively primitive: it cannot be used
     over the network, and works at the level of individual files.
     Almost everything you can do with RCS can be done through VC.

   * CVS is the free version control system that was, until recently
     (circa 2008), used by the majority of free software projects.
     Nowadays, it is slowly being superseded by newer systems.  CVS
     allows concurrent multi-user development either locally or over
     the network.  Unlike newer systems, it lacks support for atomic
     commits and file moving/renaming.  VC supports all basic editing
     operations under CVS.

   * Subversion (svn) is a free version control system designed to be
     similar to CVS but without its problems (e.g., it supports atomic
     commits of filesets, and versioning of directories, symbolic links,
     meta-data, renames, copies, and deletes).

   * GNU Arch is one of the earliest "decentralized" version control
     systems (the other being Monotone).  *Note VCS Concepts::, for a
     description of decentralized version control systems.  It is no
     longer under active development, and has been deprecated in favor
     of Bazaar.

   * Git is a decentralized version control system originally invented
     by Linus Torvalds to support development of Linux (his kernel).  VC
     supports many common Git operations, but others, such as repository
     syncing, must be done from the command line.

   * Mercurial (hg) is a decentralized version control system broadly
     resembling Git.  VC supports most Mercurial commands, with the
     exception of repository sync operations.

   * Bazaar (bzr) is a decentralized version control system that
     supports both repository-based and decentralized versioning.  VC
     supports most basic editing operations under Bazaar.


File: emacs,  Node: VCS Concepts,  Next: VCS Merging,  Prev: Version Control Systems,  Up: Introduction to VC

28.1.1.3 Concepts of Version Control
....................................

When a file is under version control, we say that it is "registered" in
the version control system.  The system has a "repository" which stores
both the file's present state and its change history--enough to
reconstruct the current version or any earlier version.  The repository
also contains other information, such as "log entries" that describe
the changes made to each file.

   The copy of a version-controlled file that you actually edit is
called the "work file".  You can change each work file as you would an
ordinary file.  After you are done with a set of changes, you may
"commit" (or "check in") the changes; this records the changes in the
repository, along with a descriptive log entry.

   A directory tree of work files is called a "working tree".

   Each commit creates a new "revision" in the repository.  The version
control system keeps track of all past revisions and the changes that
were made in each revision.  Each revision is named by a "revision ID",
whose format depends on the version control system; in the simplest
case, it is just an integer.

   To go beyond these basic concepts, you will need to understand three
aspects in which version control systems differ.  As explained in the
next three sections, they can be lock-based or merge-based; file-based
or changeset-based; and centralized or decentralized.  VC handles all
these modes of operation, but it cannot hide the differences.


File: emacs,  Node: VCS Merging,  Next: VCS Changesets,  Prev: VCS Concepts,  Up: Introduction to VC

28.1.1.4 Merge-based vs lock-based Version Control
..................................................

A version control system typically has some mechanism to coordinate
between users who want to change the same file.  There are two ways to
do this: merging and locking.

   In a version control system that uses merging, each user may modify
a work file at any time.  The system lets you "merge" your work file,
which may contain changes that have not been committed, with the latest
changes that others have committed.

   Older version control systems use a "locking" scheme instead.  Here,
work files are normally read-only.  To edit a file, you ask the version
control system to make it writable for you by "locking" it; only one
user can lock a given file at any given time.  This procedure is
analogous to, but different from, the locking that Emacs uses to detect
simultaneous editing of ordinary files (*note Interlocking::).  When
you commit your changes, that unlocks the file, and the work file
becomes read-only again.  Other users may then lock the file to make
their own changes.

   Both locking and merging systems can have problems when multiple
users try to modify the same file at the same time.  Locking systems
have "lock conflicts"; a user may try to check a file out and be unable
to because it is locked.  In merging systems, "merge conflicts" happen
when you commit a change to a file that conflicts with a change
committed by someone else after your checkout.  Both kinds of conflict
have to be resolved by human judgment and communication.  Experience
has shown that merging is superior to locking, both in convenience to
developers and in minimizing the number and severity of conflicts that
actually occur.

   SCCS always uses locking.  RCS is lock-based by default but can be
told to operate in a merging style.  CVS and Subversion are merge-based
by default but can be told to operate in a locking mode.  Decentralized
version control systems, such as GNU Arch, Git, and Mercurial, are
exclusively merging-based.

   VC mode supports both locking and merging version control.  The
terms "commit" and "update" are used in newer version control systems;
older lock-based systems use the terms "check in" and "check out".  VC
hides the differences between them as much as possible.


File: emacs,  Node: VCS Changesets,  Next: VCS Repositories,  Prev: VCS Merging,  Up: Introduction to VC

28.1.1.5 Changeset-based vs File-based Version Control
......................................................

On SCCS, RCS, CVS, and other early version control systems, version
control operations are "file-based": each file has its own comment and
revision history separate from that of all other files.  Newer systems,
beginning with Subversion, are "changeset-based": a commit may include
changes to several files, and the entire set of changes is handled as a
unit.  Any comment associated with the change does not belong to a
single file, but to the changeset itself.

   Changeset-based version control is more flexible and powerful than
file-based version control; usually, when a change to multiple files
has to be reversed, it's good to be able to easily identify and remove
all of it.


File: emacs,  Node: VCS Repositories,  Next: Types of Log File,  Prev: VCS Changesets,  Up: Introduction to VC

28.1.1.6 Decentralized vs Centralized Repositories
..................................................

Early version control systems were designed around a "centralized"
model in which each project has only one repository used by all
developers.  SCCS, RCS, CVS, and Subversion share this kind of model.
One of its drawbacks is that the repository is a choke point for
reliability and efficiency.

   GNU Arch pioneered the concept of "distributed" or "decentralized"
version control, later implemented in Git, Mercurial, and Bazaar.  A
project may have several different repositories, and these systems
support a sort of super-merge between repositories that tries to
reconcile their change histories.  In effect, there is one repository
for each developer, and repository merges take the place of commit
operations.

   VC helps you manage the traffic between your personal workfiles and
a repository.  Whether the repository is a single master, or one of a
network of peer repositories, is not something VC has to care about.


File: emacs,  Node: Types of Log File,  Prev: VCS Repositories,  Up: Introduction to VC

28.1.1.7 Types of Log File
..........................

Projects that use a version control system can have two types of log
for changes.  One is the log maintained by the version control system:
each time you commit a change, you fill out a "log entry" for the
change (*note Log Buffer::).  This is called the "version control log".

   The other kind of log is the file `ChangeLog' (*note Change Log::).
It provides a chronological record of all changes to a large portion of
a program--typically one directory and its subdirectories.  A small
program would use one `ChangeLog' file; a large program may have a
`ChangeLog' file in each major directory.  *Note Change Log::.
Programmers have used change logs since long before version control
systems.

   Changeset-based version systems typically maintain a changeset-based
modification log for the entire system, which makes change log files
somewhat redundant.  One advantage that they retain is that it is
sometimes useful to be able to view the transaction history of a single
directory separately from those of other directories.

   A project maintained with version control can use just the version
control log, or it can use both kinds of logs.  It can handle some
files one way and some files the other way.  Each project has its
policy, which you should follow.

   When the policy is to use both, you typically want to write an entry
for each change just once, then put it into both logs.  You can write
the entry in `ChangeLog', then copy it to the log buffer with `C-c C-a'
when committing the change (*note Log Buffer::).  Or you can write the
entry in the log buffer while committing the change, and later use the
`C-x v a' command to copy it to `ChangeLog' (*note Change Logs and
VC::).


File: emacs,  Node: VC Mode Line,  Next: Basic VC Editing,  Prev: Introduction to VC,  Up: Version Control

28.1.2 Version Control and the Mode Line
----------------------------------------

When you visit a file that is under version control, Emacs indicates
this on the mode line.  For example, `Bzr-1223' says that Bazaar is
used for that file, and the current revision ID is 1223.

   The character between the back-end name and the revision ID
indicates the "version control status" of the work file.  In a
merge-based version control system, a `-' character indicates that the
work file is unmodified, and `:' indicates that it has been modified.
`!' indicates that the file contains conflicts as result of a recent
merge operation (*note Merging::), or that the file was removed from
the version control.  Finally, `?'  means that the file is under
version control, but is missing from the working tree.

   In a lock-based system, `-' indicates an unlocked file, and `:' a
locked file; if the file is locked by another user (for instance,
`jim'), that is displayed as `RCS:jim:1.3'.  `@' means that the file
was locally added, but not yet committed to the master repository.

   On a graphical display, you can move the mouse over this mode line
indicator to pop up a "tool-tip", which displays a more verbose
description of the version control status.  Pressing `Mouse-1' over the
indicator pops up a menu of VC commands, identical to `Tools / Version
Control' on the menu bar.

   When Auto Revert mode (*note Reverting::) reverts a buffer that is
under version control, it updates the version control information in
the mode line.  However, Auto Revert mode may not properly update this
information if the version control status changes without changes to
the work file, from outside the current Emacs session.  If you set
`auto-revert-check-vc-info' to `t', Auto Revert mode updates the
version control status information every `auto-revert-interval'
seconds, even if the work file itself is unchanged.  The resulting CPU
usage depends on the version control system, but is usually not
excessive.


File: emacs,  Node: Basic VC Editing,  Next: Log Buffer,  Prev: VC Mode Line,  Up: Version Control

28.1.3 Basic Editing under Version Control
------------------------------------------

Most VC commands operate on "VC filesets".  A VC fileset is a
collection of one or more files that a VC operation acts on.  When you
type VC commands in a buffer visiting a version-controlled file, the VC
fileset is simply that one file.  When you type them in a VC Directory
buffer, and some files in it are marked, the VC fileset consists of the
marked files (*note VC Directory Mode::).

   On modern changeset-based version control systems (*note VCS
Changesets::), VC commands handle multi-file VC filesets as a group.
For example, committing a multi-file VC fileset generates a single
revision, containing the changes to all those files.  On older
file-based version control systems like CVS, each file in a multi-file
VC fileset is handled individually; for example, a commit generates one
revision for each changed file.

`C-x v v'
     Perform the next appropriate version control operation on the
     current VC fileset.

   The principal VC command is a multi-purpose command, `C-x v v'
(`vc-next-action'), which performs the "most appropriate" action on the
current VC fileset: either registering it with a version control
system, or committing it, or unlocking it, or merging changes into it.
The precise actions are described in detail in the following
subsections.  You can use `C-x v v' either in a file-visiting buffer or
in a VC Directory buffer.

   Note that VC filesets are distinct from the "named filesets" used
for viewing and visiting files in functional groups (*note Filesets::).
Unlike named filesets, VC filesets are not named and don't persist
across sessions.

* Menu:

* VC With A Merging VCS::  Without locking: default mode for CVS.
* VC With A Locking VCS::  RCS in its default mode, SCCS, and optionally CVS.
* Advanced C-x v v::       Advanced features available with a prefix argument.


File: emacs,  Node: VC With A Merging VCS,  Next: VC With A Locking VCS,  Up: Basic VC Editing

28.1.3.1 Basic Version Control with Merging
...........................................

On a merging-based version control system (i.e. most modern ones; *note
VCS Merging::), `C-x v v' does the following:

   * If there is more than one file in the VC fileset and the files have
     inconsistent version control statuses, signal an error.  (Note,
     however, that a fileset is allowed to include both "newly-added"
     files and "modified" files; *note Registering::.)

   * If none of the files in the VC fileset are registered with a
     version control system, register the VC fileset, i.e. place it
     under version control.  *Note Registering::.  If Emacs cannot find
     a system to register under, it prompts for a repository type,
     creates a new repository, and registers the VC fileset with it.

   * If every work file in the VC fileset is unchanged, do nothing.

   * If every work file in the VC fileset has been modified, commit the
     changes.  To do this, Emacs pops up a `*vc-log*' buffer; type the
     desired log entry for the new revision, followed by `C-c C-c' to
     commit.  *Note Log Buffer::.

     If committing to a shared repository, the commit may fail if the
     repository that has been changed since your last update.  In that
     case, you must perform an update before trying again.  On a
     decentralized version control system, use `C-x v +' (*note VC
     Pull::) or `C-x v m' (*note Merging::).  On a centralized version
     control system, type `C-x v v' again to merge in the repository
     changes.

   * Finally, if you are using a centralized version control system,
     check if each work file in the VC fileset is up-to-date.  If any
     file has been changed in the repository, offer to update it.

   These rules also apply when you use RCS in its "non-locking" mode,
except that changes are not automatically merged from the repository.
Nothing informs you if another user has committed changes in the same
file since you began editing it; when you commit your revision, his
changes are removed (however, they remain in the repository and are
thus not irrevocably lost).  Therefore, you must verify that the
current revision is unchanged before committing your changes.  In
addition, locking is possible with RCS even in this mode: `C-x v v'
with an unmodified file locks the file, just as it does with RCS in its
normal locking mode (*note VC With A Locking VCS::).


File: emacs,  Node: VC With A Locking VCS,  Next: Advanced C-x v v,  Prev: VC With A Merging VCS,  Up: Basic VC Editing

28.1.3.2 Basic Version Control with Locking
...........................................

On a locking-based version control system (such as SCCS, and RCS in its
default mode), `C-x v v' does the following:

   * If there is more than one file in the VC fileset and the files have
     inconsistent version control statuses, signal an error.

   * If each file in the VC fileset is not registered with a version
     control system, register the VC fileset.  *Note Registering::.  If
     Emacs cannot find a system to register under, it prompts for a
     repository type, creates a new repository, and registers the VC
     fileset with it.

   * If each file is registered and unlocked, lock it and make it
     writable, so that you can begin to edit it.

   * If each file is locked by you and contains changes, commit the
     changes.  To do this, Emacs pops up a `*vc-log*' buffer; type the
     desired log entry for the new revision, followed by `C-c C-c' to
     commit (*note Log Buffer::).

   * If each file is locked by you, but you have not changed it, release
     the lock and make the file read-only again.

   * If each file is locked by another user, ask whether you want to
     "steal the lock".  If you say yes, the file becomes locked by you,
     and a warning message is sent to the user who had formerly locked
     the file.

   These rules also apply when you use CVS in locking mode, except that
CVS does not support stealing locks.


File: emacs,  Node: Advanced C-x v v,  Prev: VC With A Locking VCS,  Up: Basic VC Editing

28.1.3.3 Advanced Control in `C-x v v'
......................................

When you give a prefix argument to `vc-next-action' (`C-u C-x v v'), it
still performs the next logical version control operation, but accepts
additional arguments to specify precisely how to do the operation.

   * You can specify the name of a version control system.  This is
     useful if the fileset can be managed by more than one version
     control system, and Emacs fails to detect the correct one.

   * Otherwise, if using CVS or RCS, you can specify a revision ID.

     If the fileset is modified (or locked), this makes Emacs commit
     with that revision ID.  You can create a new branch by supplying an
     appropriate revision ID (*note Branches::).

     If the fileset is unmodified (and unlocked), this checks the
     specified revision into the working tree.  You can also specify a
     revision on another branch by giving its revision or branch ID
     (*note Switching Branches::).  An empty argument (i.e. `C-u C-x v
     v <RET>') checks out the latest ("head") revision on the current
     branch.

     This signals an error on a decentralized version control system.
     Those systems do not let you specify your own revision IDs, nor do
     they use the concept of "checking out" individual files.


File: emacs,  Node: Log Buffer,  Next: Registering,  Prev: Basic VC Editing,  Up: Version Control

28.1.4 Features of the Log Entry Buffer
---------------------------------------

When you tell VC to commit a change, it pops up a buffer named
`*vc-log*'.  In this buffer, you should write a "log entry" describing
the changes you have made (*note Why Version Control?::).  After you
are done, type `C-c C-c' (`log-edit-done') to exit the buffer and
commit the change, together with your log entry.

   The major mode for the `*vc-log*' buffer is Log Edit mode, a variant
of Text mode (*note Text Mode::).  On entering Log Edit mode, Emacs
runs the hooks `text-mode-hook' and `vc-log-mode-hook' (*note Hooks::).

   In the `*vc-log*' buffer, you can write one or more "header lines",
specifying additional information to be supplied to the version control
system.  Each header line must occupy a single line at the top of the
buffer; the first line that is not a header line is treated as the
start of the log entry.  For example, the following header line states
that the present change was not written by you, but by another
developer:

     Author: J. R. Hacker <jrh@example.com>

Apart from the `Author' header, Emacs recognizes the headers `Date' (a
manually-specified commit time) and `Fixes' (a reference to a bug fixed
by the change).  Not all version control systems recognize all headers:
Bazaar recognizes all three headers, while Git, Mercurial, and Monotone
recognize only `Author' and `Date'.  If you specify a header for a
system that does not support it, the header is treated as part of the
log entry.

   While in the `*vc-log*' buffer, the "current VC fileset" is
considered to be the fileset that will be committed if you type
`C-c C-c'.  To view a list of the files in the VC fileset, type
`C-c C-f' (`log-edit-show-files').  To view a diff of changes between
the VC fileset and the version from which you started editing (*note
Old Revisions::), type `C-c C-d' (`log-edit-show-diff').

   If the VC fileset includes one or more `ChangeLog' files (*note
Change Log::), type `C-c C-a' (`log-edit-insert-changelog') to pull the
relevant entries into the `*vc-log*' buffer.  If the topmost item in
each `ChangeLog' was made under your user name on the current date,
this command searches that item for entries matching the file(s) to be
committed, and inserts them.  If you are using CVS or RCS, see *note
Change Logs and VC::, for the opposite way of working--generating
ChangeLog entries from the Log Edit buffer.

   To abort a commit, just *don't* type `C-c C-c' in that buffer.  You
can switch buffers and do other editing.  As long as you don't try to
make another commit, the entry you were editing remains in the
`*vc-log*' buffer, and you can go back to that buffer at any time to
complete the commit.

   You can also browse the history of previous log entries to duplicate
a commit comment.  This can be useful when you want to make several
commits with similar comments.  The commands `M-n', `M-p', `M-s' and
`M-r' for doing this work just like the minibuffer history commands
(*note Minibuffer History::), except that they are used outside the
minibuffer.


File: emacs,  Node: Registering,  Next: Old Revisions,  Prev: Log Buffer,  Up: Version Control

28.1.5 Registering a File for Version Control
---------------------------------------------

`C-x v i'
     Register the visited file for version control.

   The command `C-x v i' (`vc-register') "registers" each file in the
current VC fileset, placing it under version control.  This is
essentially equivalent to the action of `C-x v v' on an unregistered VC
fileset (*note Basic VC Editing::), except that if the VC fileset is
already registered, `C-x v i' signals an error whereas `C-x v v'
performs some other action.

   To register a file, Emacs must choose a version control system.  For
a multi-file VC fileset, the VC Directory buffer specifies the system
to use (*note VC Directory Mode::).  For a single-file VC fileset, if
the file's directory already contains files registered in a version
control system, or if the directory is part of a directory tree
controlled by a version control system, Emacs chooses that system.  In
the event that more than one version control system is applicable,
Emacs uses the one that appears first in the variable
`vc-handled-backends' (*note Customizing VC::).  If Emacs cannot find a
version control system to register the file under, it prompts for a
repository type, creates a new repository, and registers the file into
that repository.

   On most version control systems, registering a file with `C-x v i'
or `C-x v v' adds it to the "working tree" but not to the repository.
Such files are labeled as `added' in the VC Directory buffer, and show
a revision ID of `@@' in the mode line.  To make the registration take
effect in the repository, you must perform a commit (*note Basic VC
Editing::).  Note that a single commit can include both file additions
and edits to existing files.

   On a locking-based version control system (*note VCS Merging::),
registering a file leaves it unlocked and read-only.  Type `C-x v v' to
start editing it.


File: emacs,  Node: Old Revisions,  Next: VC Change Log,  Prev: Registering,  Up: Version Control

28.1.6 Examining And Comparing Old Revisions
--------------------------------------------

`C-x v ='
     Compare the work files in the current VC fileset with the versions
     you started from (`vc-diff').  With a prefix argument, prompt for
     two revisions of the current VC fileset and compare them.  You can
     also call this command from a Dired buffer (*note Dired::).

`M-x vc-ediff'
     Like `C-x v =', but using Ediff.  *Note Ediff: (ediff)Top.

`C-x v D'
     Compare the entire working tree to the revision you started from
     (`vc-root-diff').  With a prefix argument, prompt for two
     revisions and compare their trees.

`C-x v ~'
     Prompt for a revision of the current file, and visit it in a
     separate buffer (`vc-revision-other-window').

`C-x v g'
     Display an annotated version of the current file: for each line,
     show the latest revision in which it was modified (`vc-annotate').

   `C-x v =' (`vc-diff') displays a "diff" which compares each work
file in the current VC fileset to the version(s) from which you started
editing.  The diff is displayed in another window, in a Diff mode
buffer (*note Diff Mode::) named `*vc-diff*'.  The usual Diff mode
commands are available in this buffer.  In particular, the `g'
(`revert-buffer') command performs the file comparison again,
generating a new diff.

   To compare two arbitrary revisions of the current VC fileset, call
`vc-diff' with a prefix argument: `C-u C-x v ='.  This prompts for two
revision IDs (*note VCS Concepts::), and displays a diff between those
versions of the fileset.  This will not work reliably for multi-file VC
filesets, if the version control system is file-based rather than
changeset-based (e.g. CVS), since then revision IDs for different files
would not be related in any meaningful way.

   Instead of the revision ID, some version control systems let you
specify revisions in other formats.  For instance, under Bazaar you can
enter `date:yesterday' for the argument to `C-u C-x v =' (and related
commands) to specify the first revision committed after yesterday.  See
the documentation of the version control system for details.

   If you invoke `C-x v =' or `C-u C-x v =' from a Dired buffer (*note
Dired::), the file listed on the current line is treated as the current
VC fileset.

   `M-x vc-ediff' works like `C-x v =', except that it uses an Ediff
session.  *Note Ediff: (ediff)Top.

   `C-x v D' (`vc-root-diff') is similar to `C-x v =', but it displays
the changes in the entire current working tree (i.e. the working tree
containing the current VC fileset).  If you invoke this command from a
Dired buffer, it applies to the working tree containing the directory.

   You can customize the `diff' options that `C-x v =' and `C-x v D'
use for generating diffs.  The options used are taken from the first
non-`nil' value amongst the variables `vc-BACKEND-diff-switches',
`vc-diff-switches', and `diff-switches' (*note Comparing Files::), in
that order.  Here, BACKEND stands for the relevant version control
system, e.g. `bzr' for Bazaar.  Since `nil' means to check the next
variable in the sequence, either of the first two may use the value `t'
to mean no switches at all.  Most of the `vc-BACKEND-diff-switches'
variables default to `nil', but some default to `t'; these are for
version control systems whose `diff' implementations do not accept
common diff options, such as Subversion.

   To directly examine an older version of a file, visit the work file
and type `C-x v ~ REVISION <RET>' (`vc-revision-other-window').  This
retrieves the file version corresponding to REVISION, saves it to
`FILENAME.~REVISION~', and visits it in a separate window.

   Many version control systems allow you to view files "annotated"
with per-line revision information, by typing `C-x v g'
(`vc-annotate').  This creates a new buffer (the "annotate buffer")
displaying the file's text, with each line colored to show how old it
is.  Red text is new, blue is old, and intermediate colors indicate
intermediate ages.  By default, the color is scaled over the full range
of ages, such that the oldest changes are blue, and the newest changes
are red.

   When you give a prefix argument to this command, Emacs reads two
arguments using the minibuffer: the revision to display and annotate
(instead of the current file contents), and the time span in days the
color range should cover.

   From the annotate buffer, these and other color scaling options are
available from the `VC-Annotate' menu.  In this buffer, you can also
use the following keys to browse the annotations of past revisions,
view diffs, or view log entries:

`p'
     Annotate the previous revision, i.e. the revision before the one
     currently annotated.  A numeric prefix argument is a repeat count,
     so `C-u 10 p' would take you back 10 revisions.

`n'
     Annotate the next revision, i.e. the revision after the one
     currently annotated.  A numeric prefix argument is a repeat count.

`j'
     Annotate the revision indicated by the current line.

`a'
     Annotate the revision before the one indicated by the current line.
     This is useful to see the state the file was in before the change
     on the current line was made.

`f'
     Show in a buffer the file revision indicated by the current line.

`d'
     Display the diff between the current line's revision and the
     previous revision.  This is useful to see what the current line's
     revision actually changed in the file.

`D'
     Display the diff between the current line's revision and the
     previous revision for all files in the changeset (for VC systems
     that support changesets).  This is useful to see what the current
     line's revision actually changed in the tree.

`l'
     Show the log of the current line's revision.  This is useful to see
     the author's description of the changes in the revision on the
     current line.

`w'
     Annotate the working revision-the one you are editing.  If you used
     `p' and `n' to browse to other revisions, use this key to return
     to your working revision.

`v'
     Toggle the annotation visibility.  This is useful for looking just
     at the file contents without distraction from the annotations.


File: emacs,  Node: VC Change Log,  Next: VC Undo,  Prev: Old Revisions,  Up: Version Control

28.1.7 VC Change Log
--------------------

`C-x v l'
     Display the change history for the current fileset
     (`vc-print-log').

`C-x v L'
     Display the change history for the current repository
     (`vc-print-root-log').

`C-x v I'
     Display the changes that a pull operation will retrieve
     (`vc-log-incoming').

`C-x v O'
     Display the changes that will be sent by the next push operation
     (`vc-log-outgoing').

   `C-x v l' (`vc-print-log') displays a buffer named
`*vc-change-log*', showing the history of changes made to the current
file, including who made the changes, the dates, and the log entry for
each change (these are the same log entries you would enter via the
`*vc-log*' buffer; *note Log Buffer::).  Point is centered at the
revision of the file currently being visited.  With a prefix argument,
the command prompts for the revision to center on, and the maximum
number of revisions to display.

   If you call `C-x v l' from a VC Directory buffer (*note VC Directory
Mode::) or a Dired buffer (*note Dired::), it applies to the file
listed on the current line.

   `C-x v L' (`vc-print-root-log') displays a `*vc-change-log*' buffer
showing the history of the entire version-controlled directory tree
(RCS, SCCS, and CVS do not support this feature).  With a prefix
argument, the command prompts for the maximum number of revisions to
display.

   The `C-x v L' history is shown in a compact form, usually showing
only the first line of each log entry.  However, you can type <RET>
(`log-view-toggle-entry-display') in the `*vc-change-log*' buffer to
reveal the entire log entry for the revision at point.  A second <RET>
hides it again.

   On a decentralized version control system, the `C-x v I'
(`vc-log-incoming') command displays a log buffer showing the changes
that will be applied, the next time you run the version control
system's "pull" command to get new revisions from another repository
(*note VC Pull::).  This other repository is the default one from which
changes are pulled, as defined by the version control system; with a
prefix argument, `vc-log-incoming' prompts for a specific repository.
Similarly, `C-x v O' (`vc-log-outgoing') shows the changes that will be
sent to another repository, the next time you run the "push" command;
with a prefix argument, it prompts for a specific destination
repository.

   In the `*vc-change-log*' buffer, you can use the following keys to
move between the logs of revisions and of files, and to examine and
compare past revisions (*note Old Revisions::):

`p'
     Move to the previous revision entry.  (Revision entries in the log
     buffer are usually in reverse-chronological order, so the previous
     revision-item usually corresponds to a newer revision.)  A numeric
     prefix argument is a repeat count.

`n'
     Move to the next revision entry.  A numeric prefix argument is a
     repeat count.

`P'
     Move to the log of the previous file, if showing logs for a
     multi-file VC fileset.  Otherwise, just move to the beginning of
     the log.  A numeric prefix argument is a repeat count.

`N'
     Move to the log of the next file, if showing logs for a multi-file
     VC fileset.  A numeric prefix argument is a repeat count.

`a'
     Annotate the revision on the current line (*note Old Revisions::).

`e'
     Modify the change comment displayed at point.  Note that not all VC
     systems support modifying change comments.

`f'
     Visit the revision indicated at the current line.

`d'
     Display a diff between the revision at point and the next earlier
     revision, for the specific file.

`D'
     Display the changeset diff between the revision at point and the
     next earlier revision.  This shows the changes to all files made
     in that revision.

`<RET>'
     In a compact-style log buffer (e.g. the one created by `C-x v L'),
     toggle between showing and hiding the full log entry for the
     revision at point.

   Because fetching many log entries can be slow, the `*vc-change-log*'
buffer displays no more than 2000 revisions by default.  The variable
`vc-log-show-limit' specifies this limit; if you set the value to zero,
that removes the limit.  You can also increase the number of revisions
shown in an existing `*vc-change-log*' buffer by clicking on the `Show
2X entries' or `Show unlimited entries' buttons at the end of the
buffer.  However, RCS, SCCS, and CVS do not support this feature.


File: emacs,  Node: VC Undo,  Next: VC Directory Mode,  Prev: VC Change Log,  Up: Version Control

28.1.8 Undoing Version Control Actions
--------------------------------------

`C-x v u'
     Revert the work file(s) in the current VC fileset to the last
     revision (`vc-revert').

   If you want to discard all the changes you have made to the current
VC fileset, type `C-x v u' (`vc-revert-buffer').  This shows you a diff
between the work file(s) and the revision from which you started
editing, and asks for confirmation for discarding the changes.  If you
agree, the fileset is reverted.  If you don't want `C-x v u' to show a
diff, set the variable `vc-revert-show-diff' to `nil' (you can still
view the diff directly with `C-x v ='; *note Old Revisions::).  Note
that `C-x v u' cannot be reversed with the usual undo commands (*note
Undo::), so use it with care.

   On locking-based version control systems, `C-x v u' leaves files
unlocked; you must lock again to resume editing.  You can also use `C-x
v u' to unlock a file if you lock it and then decide not to change it.


File: emacs,  Node: VC Directory Mode,  Next: Branches,  Prev: VC Undo,  Up: Version Control

28.1.9 VC Directory Mode
------------------------

The "VC Directory buffer" is a specialized buffer for viewing the
version control statuses of the files in a directory tree, and
performing version control operations on those files.  In particular,
it is used to specify multi-file VC filesets for commands like
`C-x v v' to act on (*note VC Directory Commands::).

   To use the VC Directory buffer, type `C-x v d' (`vc-dir').  This
reads a directory name using the minibuffer, and switches to a VC
Directory buffer for that directory.  By default, the buffer is named
`*vc-dir*'.  Its contents are described in *note VC Directory Buffer::.

   The `vc-dir' command automatically detects the version control
system to be used in the specified directory.  In the event that more
than one system is being used in the directory, you should invoke the
command with a prefix argument, `C-u C-x v d'; this prompts for the
version control system which the VC Directory buffer should use.

   In addition to the VC Directory buffer, Emacs has a similar facility
called PCL-CVS which is specialized for CVS.  *Note About PCL-CVS:
(pcl-cvs)Top.

* Menu:

* Buffer: VC Directory Buffer.      What the buffer looks like and means.
* Commands: VC Directory Commands.  Commands to use in a VC directory buffer.


File: emacs,  Node: VC Directory Buffer,  Next: VC Directory Commands,  Up: VC Directory Mode

28.1.9.1 The VC Directory Buffer
................................

The VC Directory buffer contains a list of version-controlled files and
their version control statuses.  It lists files in the current
directory (the one specified when you called `C-x v d') and its
subdirectories, but only those with a "noteworthy" status.  Files that
are up-to-date (i.e. the same as in the repository) are omitted.  If
all the files in a subdirectory are up-to-date, the subdirectory is not
listed either.  As an exception, if a file has become up-to-date as a
direct result of a VC command, it is listed.

   Here is an example of a VC Directory buffer listing:

                          ./
         edited           configure.ac
     *   added            README
         unregistered     temp.txt
                          src/
     *   edited           src/main.c

Two work files have been modified but not committed: `configure.ac' in
the current directory, and `foo.c' in the `src/' subdirectory.  The
file named `README' has been added but is not yet committed, while
`temp.txt' is not under version control (*note Registering::).

   The `*' characters next to the entries for `README' and `src/main.c'
indicate that the user has marked out these files as the current VC
fileset (*note VC Directory Commands::).

   The above example is typical for a decentralized version control
system like Bazaar, Git, or Mercurial.  Other systems can show other
statuses.  For instance, CVS shows the `needs-update' status if the
repository has changes that have not been applied to the work file.
RCS and SCCS show the name of the user locking a file as its status.

   On CVS and Subversion, the `vc-dir' command normally contacts the
repository, which may be on a remote machine, to check for updates.  If
you change the variable `vc-stay-local' or `vc-cvs-stay-local' (for
CVS) to `nil' (*note CVS Options::), then Emacs avoids contacting a
remote repository when generating the VC Directory buffer (it will
still contact it when necessary, e.g. when doing a commit).  This may
be desirable if you are working offline or the network is slow.

   The VC Directory buffer omits subdirectories listed in the variable
`vc-directory-exclusion-list'.  Its default value contains directories
that are used internally by version control systems.


File: emacs,  Node: VC Directory Commands,  Prev: VC Directory Buffer,  Up: VC Directory Mode

28.1.9.2 VC Directory Commands
..............................

Emacs provides several commands for navigating the VC Directory buffer,
and for "marking" files as belonging to the current VC fileset.

`n'
`<SPC>'
     Move point to the next entry (`vc-dir-next-line').

`p'
     Move point to the previous entry (`vc-dir-previous-line').

`<TAB>'
     Move to the next directory entry (`vc-dir-next-directory').

`S-<TAB>'
     Move to the previous directory entry (`vc-dir-previous-directory').

`<RET>'
`f'
     Visit the file or directory listed on the current line
     (`vc-dir-find-file').

`o'
     Visit the file or directory on the current line, in a separate
     window (`vc-dir-find-file-other-window').

`m'
     Mark the file or directory on the current line (`vc-dir-mark'),
     putting it in the current VC fileset.  If the region is active,
     mark all files in the region.

     A file cannot be marked with this command if it is already in a
     marked directory, or one of its subdirectories.  Similarly, a
     directory cannot be marked with this command if any file in its
     tree is marked.

`M'
     If point is on a file entry, mark all files with the same status;
     if point is on a directory entry, mark all files in that directory
     tree (`vc-dir-mark-all-files').  With a prefix argument, mark all
     listed files and directories.

`q'
     Bury the VC Directory buffer, and delete its window if the window
     was created just for that buffer.

`u'
     Unmark the file or directory on the current line.  If the region is
     active, unmark all the files in the region (`vc-dir-unmark').

`U'
     If point is on a file entry, unmark all files with the same
     status; if point is on a directory entry, unmark all files in that
     directory tree (`vc-dir-unmark-all-files').  With a prefix
     argument, unmark all files and directories.

`x'
     Hide files with `up-to-date' status (`vc-dir-hide-up-to-date').

`q'
     Quit the VC Directory buffer, and bury it (`quit-window').

   While in the VC Directory buffer, all the files that you mark with
`m' (`vc-dir-mark') or `M' (`vc-dir-mark') are in the current VC
fileset.  If you mark a directory entry with `m', all the listed files
in that directory tree are in the current VC fileset.  The files and
directories that belong to the current VC fileset are indicated with a
`*' character in the VC Directory buffer, next to their VC status.  In
this way, you can set up a multi-file VC fileset to be acted on by VC
commands like `C-x v v' (*note Basic VC Editing::), `C-x v =' (*note
Old Revisions::), and `C-x v u' (*note VC Undo::).

   The VC Directory buffer also defines some single-key shortcuts for
VC commands with the `C-x v' prefix: `=', `+', `l', `i', and `v'.

   For example, you can commit a set of edited files by opening a VC
Directory buffer, where the files are listed with the `edited' status;
marking the files; and typing `v' or `C-x v v' (`vc-next-action').  If
the version control system is changeset-based, Emacs will commit the
files in a single revision.

   While in the VC Directory buffer, you can also perform search and
replace on the current VC fileset, with the following commands:

`S'
     Search the fileset (`vc-dir-search').

`Q'
     Do a regular expression query replace on the fileset
     (`vc-dir-query-replace-regexp').

`M-s a C-s'
     Do an incremental search on the fileset (`vc-dir-isearch').

`M-s a C-M-s'
     Do an incremental regular expression search on the fileset
     (`vc-dir-isearch-regexp').

Apart from acting on multiple files, these commands behave much like
their single-buffer counterparts (*note Search::).

   The above commands are also available via the menu bar, and via a
context menu invoked by `Mouse-2'.  Furthermore, some VC backends use
the menu to provide extra backend-specific commands.  For example, Git
and Bazaar allow you to manipulate "stashes" and "shelves" (where are a
way to temporarily put aside uncommitted changes, and bring them back
at a later time).


File: emacs,  Node: Branches,  Next: Miscellaneous VC,  Prev: VC Directory Mode,  Up: Version Control

28.1.10 Version Control Branches
--------------------------------

One use of version control is to support multiple independent lines of
development, which are called "branches".  Branches are used for
maintaining separate "stable" and "development" versions of a program,
and for developing unrelated features in isolation from one another.

   VC's support for branch operations is currently fairly limited.  For
decentralized version control systems, it provides commands for
"updating" one branch with the contents of another, and for "merging"
the changes made to two different branches (*note Merging::).  For
centralized version control systems, it supports checking out different
branches and committing into new or different branches.

* Menu:

* Switching Branches::    How to get to another existing branch.
* VC Pull::               Updating the contents of a branch.
* Merging::               Transferring changes between branches.
* Creating Branches::     How to start a new branch.


File: emacs,  Node: Switching Branches,  Next: VC Pull,  Up: Branches

28.1.10.1 Switching between Branches
....................................

The various version control systems differ in how branches are
implemented, and these differences cannot be entirely concealed by VC.

   On some decentralized version control systems, including Bazaar and
Mercurial in its normal mode of operation, each branch has its own
working directory tree, so switching between branches just involves
switching directories.  On Git, switching between branches is done
using the `git branch' command, which changes the contents of the
working tree itself.

   On centralized version control systems, you can switch between
branches by typing `C-u C-x v v' in an up-to-date work file (*note
Advanced C-x v v::), and entering the revision ID for a revision on
another branch.  On CVS, for instance, revisions on the "trunk" (the
main line of development) normally have IDs of the form 1.1, 1.2, 1.3,
..., while the first branch created from (say) revision 1.2 has
revision IDs 1.2.1.1, 1.2.1.2, ..., the second branch created from
revision 1.2 has revision IDs 1.2.2.1, 1.2.2.2, ..., and so forth.  You
can also specify the "branch ID", which is a branch revision ID
omitting its final component (e.g. 1.2.1), to switch to the latest
revision on that branch.

   On a locking-based system, switching to a different branch also
unlocks (write-protects) the working tree.

   Once you have switched to a branch, VC commands will apply to that
branch until you switch away; for instance, any VC filesets that you
commit will be committed to that specific branch.


File: emacs,  Node: VC Pull,  Next: Merging,  Prev: Switching Branches,  Up: Branches

28.1.10.2 Pulling Changes into a Branch
.......................................

`C-x v +'
     On a decentralized version control system, update the current
     branch by "pulling in" changes from another location.

     On a centralized version control system, update the current VC
     fileset.

   On a decentralized version control system, the command `C-x v +'
(`vc-pull') updates the current branch and working tree.  It is
typically used to update a copy of a remote branch.  If you supply a
prefix argument, the command prompts for the exact version control
command to use, which lets you specify where to pull changes from.
Otherwise, it pulls from a default location determined by the version
control system.

   Amongst decentralized version control systems, `C-x v +' is
currently supported only by Bazaar, Git, and Mercurial.  On Bazaar, it
calls `bzr pull' for ordinary branches (to pull from a master branch
into a mirroring branch), and `bzr update' for a bound branch (to pull
from a central repository).  On Git, it calls `git pull' to fetch
changes from a remote repository and merge it into the current branch.
On Mercurial, it calls `hg pull -u' to fetch changesets from the
default remote repository and update the working directory.

   Prior to pulling, you can use `C-x v I' (`vc-log-incoming') to view
a log buffer of the changes to be applied.  *Note VC Change Log::.

   On a centralized version control system like CVS, `C-x v +' updates
the current VC fileset from the repository.


File: emacs,  Node: Merging,  Next: Creating Branches,  Prev: VC Pull,  Up: Branches

28.1.10.3 Merging Branches
..........................

`C-x v m'
     On a decentralized version control system, merge changes from
     another branch into the current one.

     On a centralized version control system, merge changes from another
     branch into the current VC fileset.

   While developing a branch, you may sometimes need to "merge" in
changes that have already been made in another branch.  This is not a
trivial operation, as overlapping changes may have been made to the two
branches.

   On a decentralized version control system, merging is done with the
command `C-x v m' (`vc-merge').  On Bazaar, this prompts for the exact
arguments to pass to `bzr merge', offering a sensible default if
possible.  On Git, this prompts for the name of a branch to merge from,
with completion (based on the branch names known to the current
repository).  The output from running the merge command is shown in a
separate buffer.

   On a centralized version control system like CVS, `C-x v m' prompts
for a branch ID, or a pair of revision IDs (*note Switching
Branches::); then it finds the changes from that branch, or the changes
between the two revisions you specified, and merges those changes into
the current VC fileset.  If you just type <RET>, Emacs simply merges
any changes that were made on the same branch since you checked the
file out.

   Immediately after performing a merge, only the working tree is
modified, and you can review the changes produced by the merge with
`C-x v D' and related commands (*note Old Revisions::).  If the two
branches contained overlapping changes, merging produces a "conflict";
a warning appears in the output of the merge command, and "conflict
markers" are inserted into each affected work file, surrounding the two
sets of conflicting changes.  You must then resolve the conflict by
editing the conflicted files.  Once you are done, the modified files
must be committed in the usual way for the merge to take effect (*note
Basic VC Editing::).


File: emacs,  Node: Creating Branches,  Prev: Merging,  Up: Branches

28.1.10.4 Creating New Branches
...............................

On centralized version control systems like CVS, Emacs supports
creating new branches as part of a commit operation.  When committing a
modified VC fileset, type `C-u C-x v v' (`vc-next-action' with a prefix
argument; *note Advanced C-x v v::).  Then Emacs prompts for a revision
ID for the new revision.  You should specify a suitable branch ID for a
branch starting at the current revision.  For example, if the current
revision is 2.5, the branch ID should be 2.5.1, 2.5.2, and so on,
depending on the number of existing branches at that point.

   To create a new branch at an older revision (one that is no longer
the head of a branch), first select that revision (*note Switching
Branches::).  Your procedure will then differ depending on whether you
are using a locking or merging-based VCS.

   On a locking VCS, you will need to lock the old revision branch with
`C-x v v'.  You'll be asked to confirm, when you lock the old revision,
that you really mean to create a new branch--if you say no, you'll be
offered a chance to lock the latest revision instead.  On a
merging-based VCS you will skip this step.

   Then make your changes and type `C-x v v' again to commit a new
revision.  This creates a new branch starting from the selected
revision.

   After the branch is created, subsequent commits create new revisions
on that branch.  To leave the branch, you must explicitly select a
different revision with `C-u C-x v v'.


File: emacs,  Node: Miscellaneous VC,  Next: Customizing VC,  Prev: Branches,  Up: Version Control

28.1.11 Miscellaneous Commands and Features of VC
-------------------------------------------------

This section explains the less-frequently-used features of VC.

* Menu:

* Change Logs and VC::  Generating a change log file from log entries.
* VC Delete/Rename::    Deleting and renaming version-controlled files.
* Revision Tags::       Symbolic names for revisions.
* Version Headers::     Inserting version control headers into working files.


File: emacs,  Node: Change Logs and VC,  Next: VC Delete/Rename,  Up: Miscellaneous VC

28.1.11.1 Change Logs and VC
............................

If you use RCS or CVS for a program with a `ChangeLog' file (*note
Change Log::), you can generate change log entries from the version
control log entries of previous commits.

   Note that this only works with RCS or CVS.  This procedure would be
particularly incorrect on a modern changeset-based version control
system, where changes to the `ChangeLog' file would normally be
committed as part of a changeset.  In that case, you should write the
change log entries first, then pull them into the `*vc-log*' buffer
when you commit (*note Log Buffer::).

`C-x v a'
     Visit the current directory's `ChangeLog' file and, for registered
     files in that directory, create new entries for versions committed
     since the most recent change log entry (`vc-update-change-log').

`C-u C-x v a'
     As above, but only find entries for the current buffer's file.

   For example, suppose the first line of `ChangeLog' is dated
1999-04-10, and that the only check-in since then was by Nathaniel
Bowditch to `rcs2log' on 1999-05-22 with log entry `Ignore log messages
that start with `#'.'.  Then `C-x v a' inserts this `ChangeLog' entry:

     1999-05-22  Nathaniel Bowditch  <nat@apn.org>

             * rcs2log: Ignore log messages that start with `#'.

If the version control log entry specifies a function name (in
parenthesis at the beginning of a line), that is reflected in the
`ChangeLog' entry.  For example, if a log entry for `vc.el' is
`(vc-do-command): Check call-process status.', the `ChangeLog' entry is:

     1999-05-06  Nathaniel Bowditch  <nat@apn.org>

             * vc.el (vc-do-command): Check call-process status.

   When `C-x v a' adds several change log entries at once, it groups
related log entries together if they all are checked in by the same
author at nearly the same time.  If the log entries for several such
files all have the same text, it coalesces them into a single entry.


File: emacs,  Node: VC Delete/Rename,  Next: Revision Tags,  Prev: Change Logs and VC,  Up: Miscellaneous VC

28.1.11.2 Deleting and Renaming Version-Controlled Files
........................................................

`M-x vc-delete-file'
     Prompt for a file name, delete the file from the working tree, and
     schedule the deletion for committing.

`M-x vc-rename-file'
     Prompt for two file names, VAR and OLD, rename them in the working
     tree, and schedule the renaming for committing.

   If you wish to delete a version-controlled file, use the command
`M-x vc-delete-file'.  This prompts for the file name, and deletes it
via the version control system.  The file is removed from the working
tree, and in the VC Directory buffer (*note VC Directory Mode::), it is
displayed with the `removed' status.  When you commit it, the deletion
takes effect in the repository.

   To rename a version-controlled file, type `M-x vc-rename-file'.
This prompts for two arguments: the name of the file you wish to
rename, and the new name; then it performs the renaming via the version
control system.  The renaming takes effect immediately in the working
tree, and takes effect in the repository when you commit the renamed
file.

   On modern version control systems that have built-in support for
renaming, the renamed file retains the full change history of the
original file.  On CVS and older version control systems, the
`vc-rename-file' command actually works by creating a copy of the old
file under the new name, registering it, and deleting the old file.  In
this case, the change history is not preserved.


File: emacs,  Node: Revision Tags,  Next: Version Headers,  Prev: VC Delete/Rename,  Up: Miscellaneous VC

28.1.11.3 Revision Tags
.......................

Most version control systems allow you to apply a "revision tag" to a
specific version of a version-controlled tree.  On modern
changeset-based version control systems, a revision tag is simply a
symbolic name for a particular revision.  On older file-based systems
like CVS, each tag is added to the entire set of version-controlled
files, allowing them to be handled as a unit.  Revision tags are
commonly used to identify releases that are distributed to users.

   There are two basic commands for tags; one makes a tag with a given
name, the other retrieves a named tag.

`C-x v s NAME <RET>'
     Define the working revision of every registered file in or under
     the current directory as a tag named NAME (`vc-create-tag').

`C-x v r NAME <RET>'
     For all registered files at or below the current directory level,
     retrieve the tagged revision NAME. This command will switch to a
     branch if NAME is a branch name and your VCS distinguishes
     branches from tags.  (`vc-retrieve-tag').

     This command reports an error if any files are locked at or below
     the current directory, without changing anything; this is to avoid
     overwriting work in progress.

   You can give a tag or branch name as an argument to `C-x v =' or
`C-x v ~' (*note Old Revisions::).  Thus, you can use it to compare a
tagged version against the current files, or two tagged versions
against each other.

   On SCCS, VC implements tags itself; these tags are visible only
through VC.  Most later systems (including CVS, Subversion, bzr, git,
and hg) have a native tag facility, and VC uses it where available;
those tags will be visible even when you bypass VC.

   In a file-oriented VCS, when you rename a registered file you need
to rename its master along with it; the command `vc-rename-file' will
do this automatically.  If you are using SCCS, you must also update the
records of the tag, to mention the file by its new name
(`vc-rename-file' does this, too).  An old tag that refers to a master
file that no longer exists under the recorded name is invalid; VC can
no longer retrieve it.  It would be beyond the scope of this manual to
explain enough about RCS and SCCS to explain how to update the tags by
hand.  Using `vc-rename-file' makes the tag remain valid for retrieval,
but it does not solve all problems.  For example, some of the files in
your program probably refer to others by name.  At the very least, the
makefile probably mentions the file that you renamed.  If you retrieve
an old tag, the renamed file is retrieved under its new name, which is
not the name that the makefile expects.  So the program won't really
work as retrieved.


File: emacs,  Node: Version Headers,  Prev: Revision Tags,  Up: Miscellaneous VC

28.1.11.4 Inserting Version Control Headers
...........................................

On Subversion, CVS, RCS, and SCCS, you can put certain special strings
called "version headers" into a work file.  When the file is committed,
the version control system automatically puts the revision number, the
name of the user who made the commit, and other relevant information
into the version header.

   VC does not normally use the information in the version headers.  As
an exception, when using RCS, Emacs uses the version header, if there
is one, to determine the file version, since it is often more reliable
than the RCS master file.  To inhibit using the version header this
way, change the variable `vc-consult-headers' to `nil'.

   To insert a suitable header string into the current buffer, type
`C-x v h' (`vc-insert-headers').  This command works only on
Subversion, CVS, RCS, and SCCS.  The variable `vc-BACKEND-header'
contains the list of keywords to insert into the version header; for
instance, CVS uses `vc-cvs-header', whose default value is
`'("\$Id\$")'.  (The extra backslashes prevent the string constant from
being interpreted as a header, if the Emacs Lisp file defining it is
maintained with version control.)  The `C-x v h' command inserts each
keyword in the list on a new line at point, surrounded by tabs, and
inside comment delimiters if necessary.

   The variable `vc-static-header-alist' specifies further strings to
add based on the name of the buffer.  Its value should be a list of
elements of the form `(REGEXP . FORMAT)'.  Whenever REGEXP matches the
buffer name, FORMAT is also inserted as part of the version header.  A
`%s' in FORMAT is replaced with the file's version control type.


File: emacs,  Node: Customizing VC,  Prev: Miscellaneous VC,  Up: Version Control

28.1.12 Customizing VC
----------------------

The variable `vc-handled-backends' determines which version control
systems VC should handle.  The default value is `(RCS CVS SVN SCCS Bzr
Git Hg Mtn Arch)', so it contains all the version systems that are
currently supported.  If you want VC to ignore one or more of these
systems, exclude its name from the list.  To disable VC entirely, set
this variable to `nil'.

   The order of systems in the list is significant: when you visit a
file registered in more than one system, VC uses the system that comes
first in `vc-handled-backends' by default.  The order is also
significant when you register a file for the first time (*note
Registering::).

* Menu:

* General VC Options::  Options that apply to multiple back ends.
* RCS and SCCS::        Options for RCS and SCCS.
* CVS Options::         Options for CVS.


File: emacs,  Node: General VC Options,  Next: RCS and SCCS,  Up: Customizing VC

28.1.12.1 General Options
.........................

Emacs normally does not save backup files for source files that are
maintained with version control.  If you want to make backup files even
for files that use version control, set the variable
`vc-make-backup-files' to a non-`nil' value.

   Editing a version-controlled file through a symbolic link may cause
unexpected results, if you are unaware that the underlying file is
version-controlled.  The variable `vc-follow-symlinks' controls what
Emacs does if you try to visit a symbolic link pointing to a
version-controlled file.  If the value is `ask' (the default), Emacs
asks for confirmation.  If it is `nil', Emacs just displays a warning
message.  If it is `t', Emacs automatically follows the link and visits
the real file instead.

   If `vc-suppress-confirm' is non-`nil', then `C-x v v' and `C-x v i'
can save the current buffer without asking, and `C-x v u' also operates
without asking for confirmation.

   VC mode does much of its work by running the shell commands for the
appropriate version control system.  If `vc-command-messages' is
non-`nil', VC displays messages to indicate which shell commands it
runs, and additional messages when the commands finish.

   You can specify additional directories to search for version control
programs by setting the variable `vc-path'.  These directories are
searched before the usual search path.  It is rarely necessary to set
this variable, because VC normally finds the proper files automatically.


File: emacs,  Node: RCS and SCCS,  Next: CVS Options,  Prev: General VC Options,  Up: Customizing VC

28.1.12.2 Options for RCS and SCCS
..................................

By default, RCS uses locking to coordinate the activities of several
users, but there is a mode called "non-strict locking" in which you can
check-in changes without locking the file first.  Use `rcs -U' to
switch to non-strict locking for a particular file, see the `rcs'
manual page for details.

   When deducing the version control state of an RCS file, VC first
looks for an RCS version header string in the file (*note Version
Headers::).  If there is no header string, VC normally looks at the
file permissions of the work file; this is fast.  But there might be
situations when the file permissions cannot be trusted.  In this case
the master file has to be consulted, which is rather expensive.  Also
the master file can only tell you _if_ there's any lock on the file,
but not whether your work file really contains that locked version.

   You can tell VC not to use version headers to determine the file
status by setting `vc-consult-headers' to `nil'.  VC then always uses
the file permissions (if it is supposed to trust them), or else checks
the master file.

   You can specify the criterion for whether to trust the file
permissions by setting the variable `vc-mistrust-permissions'.  Its
value can be `t' (always mistrust the file permissions and check the
master file), `nil' (always trust the file permissions), or a function
of one argument which makes the decision.  The argument is the
directory name of the `RCS' subdirectory.  A non-`nil' value from the
function says to mistrust the file permissions.  If you find that the
file permissions of work files are changed erroneously, set
`vc-mistrust-permissions' to `t'.  Then VC always checks the master
file to determine the file's status.

   VC determines the version control state of files under SCCS much as
with RCS.  It does not consider SCCS version headers, though.  Thus,
the variable `vc-mistrust-permissions' affects SCCS use, but
`vc-consult-headers' does not.


File: emacs,  Node: CVS Options,  Prev: RCS and SCCS,  Up: Customizing VC

28.1.12.3 Options specific for CVS
..................................

You can specify additional command line options to pass to all CVS
operations in the variable `vc-cvs-global-switches'.  These switches
are inserted immediately after the `cvs' command, before the name of
the operation to invoke.

   When using a CVS repository on a remote machine, VC can try keeping
network interactions to a minimum.  This is controlled by the variable
`vc-cvs-stay-local'.  There is another variable, `vc-stay-local', which
enables the feature also for other back ends that support it, including
CVS.  In the following, we will talk only about `vc-cvs-stay-local',
but everything applies to `vc-stay-local' as well.

   If `vc-cvs-stay-local' is `t' (the default), VC determines the
version control status of each file using only the entry in the local
CVS subdirectory and the information returned by previous CVS commands.
As a consequence, if you have modified a file and somebody else has
checked in other changes, you will not be notified of the conflict
until you try to commit.

   If you change `vc-cvs-stay-local' to `nil', VC queries the remote
repository _before_ it decides what to do in `vc-next-action' (`C-x v
v'), just as it does for local repositories.

   You can also set `vc-cvs-stay-local' to a regular expression that is
matched against the repository host name; VC then stays local only for
repositories from hosts that match the pattern.

   When using a remote repository, Emacs normally makes "automatic
version backups" of the original versions of each edited file.  These
local backups are made whenever you save the first changes to a file,
and they are removed after you commit your changes to the repository.
(Note that these are not the same as ordinary Emacs backup files; *note
Backup::.)  Commands like `C-x v =' and `C-x v u' make use of automatic
version backups, if possible, to avoid having to access the network.

   Setting `vc-cvs-stay-local' to `nil' disables the making of
automatic version backups.

   Automatic version backups have names of the form `FILE.~VERSION.~'.
This is similar to the name that `C-x v ~' saves old versions to (*note
Old Revisions::), except for the additional dot (`.') after the
version.  The relevant VC commands can use both kinds of version
backups.  The main difference is that the "manual" version backups made
by `C-x v ~' are not deleted automatically when you commit.

   CVS does not use locking by default, but there are ways to enable
locking-like behavior using its `CVSREAD' or "watch" feature; see the
CVS documentation for details.  If that case, you can use `C-x v v' in
Emacs to toggle locking, as you would for a locking-based version
control system (*note VC With A Locking VCS::).


File: emacs,  Node: Change Log,  Next: Tags,  Prev: Version Control,  Up: Maintaining

28.2 Change Logs
================

Many software projects keep a "change log".  This is a file, normally
named `ChangeLog', containing a chronological record of when and how
the program was changed.  Sometimes, there are several change log
files, each recording the changes in one directory or directory tree.

* Menu:

* Change Log Commands:: Commands for editing change log files.
* Format of ChangeLog:: What the change log file looks like.


File: emacs,  Node: Change Log Commands,  Next: Format of ChangeLog,  Up: Change Log

28.2.1 Change Log Commands
--------------------------

The Emacs command `C-x 4 a' adds a new entry to the change log file for
the file you are editing (`add-change-log-entry-other-window').  If
that file is actually a backup file, it makes an entry appropriate for
the file's parent--that is useful for making log entries for functions
that have been deleted in the current version.

   `C-x 4 a' visits the change log file and creates a new entry unless
the most recent entry is for today's date and your name.  It also
creates a new item for the current file.  For many languages, it can
even guess the name of the function or other object that was changed.

   When the variable `add-log-keep-changes-together' is non-`nil', `C-x
4 a' adds to any existing item for the file rather than starting a new
item.

   You can combine multiple changes of the same nature.  If you don't
enter any text after the initial `C-x 4 a', any subsequent `C-x 4 a'
adds another symbol to the change log entry.

   If `add-log-always-start-new-record' is non-`nil', `C-x 4 a' always
makes a new entry, even if the last entry was made by you and on the
same date.

   If the value of the variable `change-log-version-info-enabled' is
non-`nil', `C-x 4 a' adds the file's version number to the change log
entry.  It finds the version number by searching the first ten percent
of the file, using regular expressions from the variable
`change-log-version-number-regexp-list'.

   The change log file is visited in Change Log mode.  In this major
mode, each bunch of grouped items counts as one paragraph, and each
entry is considered a page.  This facilitates editing the entries.
`C-j' and auto-fill indent each new line like the previous line; this
is convenient for entering the contents of an entry.

   You can use the `next-error' command (by default bound to `C-x `')
to move between entries in the Change Log, when Change Log mode is on.
You will jump to the actual site in the file that was changed, not just
to the next Change Log entry.  You can also use `previous-error' to
move back in the same list.

   You can use the command `M-x change-log-merge' to merge other log
files into a buffer in Change Log Mode, preserving the date ordering of
entries.

   Version control systems are another way to keep track of changes in
your program and keep a change log.  In the VC log buffer, typing `C-c
C-a' (`log-edit-insert-changelog') inserts the relevant Change Log
entry, if one exists.  *Note Log Buffer::.


File: emacs,  Node: Format of ChangeLog,  Prev: Change Log Commands,  Up: Change Log

28.2.2 Format of ChangeLog
--------------------------

A change log entry starts with a header line that contains the current
date, your name (taken from the variable `add-log-full-name'), and your
email address (taken from the variable `add-log-mailing-address').
Aside from these header lines, every line in the change log starts with
a space or a tab.  The bulk of the entry consists of "items", each of
which starts with a line starting with whitespace and a star.  Here are
two entries, both dated in May 1993, with two items and one item
respectively.

     1993-05-25  Richard Stallman  <rms@gnu.org>

             * man.el: Rename symbols `man-*' to `Man-*'.
             (manual-entry): Make prompt string clearer.

             * simple.el (blink-matching-paren-distance):
             Change default to 12,000.

     1993-05-24  Richard Stallman  <rms@gnu.org>

             * vc.el (minor-mode-map-alist): Don't use it if it's void.
             (vc-cancel-version): Doc fix.

   One entry can describe several changes; each change should have its
own item, or its own line in an item.  Normally there should be a blank
line between items.  When items are related (parts of the same change,
in different places), group them by leaving no blank line between them.

   You should put a copyright notice and permission notice at the end
of the change log file.  Here is an example:

     Copyright 1997, 1998 Free Software Foundation, Inc.
     Copying and distribution of this file, with or without modification, are
     permitted provided the copyright notice and this notice are preserved.

Of course, you should substitute the proper years and copyright holder.


File: emacs,  Node: Tags,  Next: EDE,  Prev: Change Log,  Up: Maintaining

28.3 Tags Tables
================

A "tag" is a reference to a subunit in a program or in a document.  In
source code, tags reference syntactic elements of the program:
functions, subroutines, data types, macros, etc.  In a document, tags
reference chapters, sections, appendices, etc.  Each tag specifies the
name of the file where the corresponding subunit is defined, and the
position of the subunit's definition in that file.

   A "tags table" records the tags extracted by scanning the source
code of a certain program or a certain document.  Tags extracted from
generated files reference the original files, rather than the generated
files that were scanned during tag extraction.  Examples of generated
files include C files generated from Cweb source files, from a Yacc
parser, or from Lex scanner definitions; `.i' preprocessed C files; and
Fortran files produced by preprocessing `.fpp' source files.

   To produce a tags table, you run the `etags' shell command on a
document or the source code file.  The `etags' program writes the tags
to a "tags table file", or "tags file" in short.  The conventional name
for a tags file is `TAGS'.  *Note Create Tags Table::.

   Emacs provides many commands for searching and replacing using the
information recorded in tags tables.  For instance, the `M-.'
(`find-tag') jumps to the location of a specified function definition
in its source file.  *Note Find Tag::.

   The Ebrowse facility is similar to `etags' but specifically tailored
for C++.  *Note Ebrowse: (ebrowse)Top.  The Semantic package provides
another way to generate and use tags, separate from the `etags'
facility.  *Note Semantic::.

* Menu:

* Tag Syntax::          Tag syntax for various types of code and text files.
* Create Tags Table::   Creating a tags table with `etags'.
* Etags Regexps::       Create arbitrary tags using regular expressions.
* Select Tags Table::   How to visit a tags table.
* Find Tag::            Commands to find the definition of a specific tag.
* Tags Search::         Using a tags table for searching and replacing.
* List Tags::           Using tags for completion, and listing them.


File: emacs,  Node: Tag Syntax,  Next: Create Tags Table,  Up: Tags

28.3.1 Source File Tag Syntax
-----------------------------

Here is how tag syntax is defined for the most popular languages:

   * In C code, any C function or typedef is a tag, and so are
     definitions of `struct', `union' and `enum'.  `#define' macro
     definitions, `#undef' and `enum' constants are also tags, unless
     you specify `--no-defines' when making the tags table.  Similarly,
     global variables are tags, unless you specify `--no-globals', and
     so are struct members, unless you specify `--no-members'.  Use of
     `--no-globals', `--no-defines' and `--no-members' can make the
     tags table file much smaller.

     You can tag function declarations and external variables in
     addition to function definitions by giving the `--declarations'
     option to `etags'.

   * In C++ code, in addition to all the tag constructs of C code,
     member functions are also recognized; member variables are also
     recognized, unless you use the `--no-members' option.  Tags for
     variables and functions in classes are named `CLASS::VARIABLE' and
     `CLASS::FUNCTION'.  `operator' definitions have tag names like
     `operator+'.

   * In Java code, tags include all the constructs recognized in C++,
     plus the `interface', `extends' and `implements' constructs.  Tags
     for variables and functions in classes are named `CLASS.VARIABLE'
     and `CLASS.FUNCTION'.

   * In LaTeX documents, the arguments for `\chapter', `\section',
     `\subsection', `\subsubsection', `\eqno', `\label', `\ref',
     `\cite', `\bibitem', `\part', `\appendix', `\entry', `\index',
     `\def', `\newcommand', `\renewcommand', `\newenvironment' and
     `\renewenvironment' are tags.

     Other commands can make tags as well, if you specify them in the
     environment variable `TEXTAGS' before invoking `etags'.  The value
     of this environment variable should be a colon-separated list of
     command names.  For example,

          TEXTAGS="mycommand:myothercommand"
          export TEXTAGS

     specifies (using Bourne shell syntax) that the commands
     `\mycommand' and `\myothercommand' also define tags.

   * In Lisp code, any function defined with `defun', any variable
     defined with `defvar' or `defconst', and in general the first
     argument of any expression that starts with `(def' in column zero
     is a tag.

   * In Scheme code, tags include anything defined with `def' or with a
     construct whose name starts with `def'.  They also include
     variables set with `set!' at top level in the file.

   Several other languages are also supported:

   * In Ada code, functions, procedures, packages, tasks and types are
     tags.  Use the `--packages-only' option to create tags for
     packages only.

     In Ada, the same name can be used for different kinds of entity
     (e.g., for a procedure and for a function).  Also, for things like
     packages, procedures and functions, there is the spec (i.e. the
     interface) and the body (i.e. the implementation).  To make it
     easier to pick the definition you want, Ada tag name have suffixes
     indicating the type of entity:

    `/b'
          package body.

    `/f'
          function.

    `/k'
          task.

    `/p'
          procedure.

    `/s'
          package spec.

    `/t'
          type.

     Thus, `M-x find-tag <RET> bidule/b <RET>' will go directly to the
     body of the package `bidule', while `M-x find-tag <RET> bidule
     <RET>' will just search for any tag `bidule'.

   * In assembler code, labels appearing at the start of a line,
     followed by a colon, are tags.

   * In Bison or Yacc input files, each rule defines as a tag the
     nonterminal it constructs.  The portions of the file that contain
     C code are parsed as C code.

   * In Cobol code, tags are paragraph names; that is, any word
     starting in column 8 and followed by a period.

   * In Erlang code, the tags are the functions, records and macros
     defined in the file.

   * In Fortran code, functions, subroutines and block data are tags.

   * In HTML input files, the tags are the `title' and the `h1', `h2',
     `h3' headers.  Also, tags are `name=' in anchors and all
     occurrences of `id='.

   * In Lua input files, all functions are tags.

   * In makefiles, targets are tags; additionally, variables are tags
     unless you specify `--no-globals'.

   * In Objective C code, tags include Objective C definitions for
     classes, class categories, methods and protocols.  Tags for
     variables and functions in classes are named `CLASS::VARIABLE' and
     `CLASS::FUNCTION'.

   * In Pascal code, the tags are the functions and procedures defined
     in the file.

   * In Perl code, the tags are the packages, subroutines and variables
     defined by the `package', `sub', `my' and `local' keywords.  Use
     `--globals' if you want to tag global variables.  Tags for
     subroutines are named `PACKAGE::SUB'.  The name for subroutines
     defined in the default package is `main::SUB'.

   * In PHP code, tags are functions, classes and defines.  Vars are
     tags too, unless you use the `--no-members' option.

   * In PostScript code, the tags are the functions.

   * In Prolog code, tags are predicates and rules at the beginning of
     line.

   * In Python code, `def' or `class' at the beginning of a line
     generate a tag.

   You can also generate tags based on regexp matching (*note Etags
Regexps::) to handle other formats and languages.


File: emacs,  Node: Create Tags Table,  Next: Etags Regexps,  Prev: Tag Syntax,  Up: Tags

28.3.2 Creating Tags Tables
---------------------------

The `etags' program is used to create a tags table file.  It knows the
syntax of several languages, as described in *note Tag Syntax::.  Here
is how to run `etags':

     etags INPUTFILES...

The `etags' program reads the specified files, and writes a tags table
named `TAGS' in the current working directory.  You can optionally
specify a different file name for the tags table by using the
`--output=FILE' option; specifying `-' as a file name prints the tags
table to standard output.

   If the specified files don't exist, `etags' looks for compressed
versions of them and uncompresses them to read them.  Under MS-DOS,
`etags' also looks for file names like `mycode.cgz' if it is given
`mycode.c' on the command line and `mycode.c' does not exist.

   If the tags table becomes outdated due to changes in the files
described in it, you can update it by running the `etags' program
again.  If the tags table does not record a tag, or records it for the
wrong file, then Emacs will not be able to find that definition until
you update the tags table.  But if the position recorded in the tags
table becomes a little bit wrong (due to other editing), Emacs will
still be able to find the right position, with a slight delay.

   Thus, there is no need to update the tags table after each edit.
You should update a tags table when you define new tags that you want
to have listed, or when you move tag definitions from one file to
another, or when changes become substantial.

   You can make a tags table "include" another tags table, by passing
the `--include=FILE' option to `etags'.  It then covers all the files
covered by the included tags file, as well as its own.

   If you specify the source files with relative file names when you run
`etags', the tags file will contain file names relative to the
directory where the tags file was initially written.  This way, you can
move an entire directory tree containing both the tags file and the
source files, and the tags file will still refer correctly to the source
files.  If the tags file is `-' or is in the `/dev' directory, however,
the file names are made relative to the current working directory.
This is useful, for example, when writing the tags to `/dev/stdout'.

   When using a relative file name, it should not be a symbolic link
pointing to a tags file in a different directory, because this would
generally render the file names invalid.

   If you specify absolute file names as arguments to `etags', then the
tags file will contain absolute file names.  This way, the tags file
will still refer to the same files even if you move it, as long as the
source files remain in the same place.  Absolute file names start with
`/', or with `DEVICE:/' on MS-DOS and MS-Windows.

   When you want to make a tags table from a great number of files, you
may have problems listing them on the command line, because some
systems have a limit on its length.  You can circumvent this limit by
telling `etags' to read the file names from its standard input, by
typing a dash in place of the file names, like this:

     find . -name "*.[chCH]" -print | etags -

   `etags' recognizes the language used in an input file based on its
file name and contents.  You can specify the language explicitly with
the `--language=NAME' option.  You can intermix these options with file
names; each one applies to the file names that follow it.  Specify
`--language=auto' to tell `etags' to resume guessing the language from
the file names and file contents.  Specify `--language=none' to turn off
language-specific processing entirely; then `etags' recognizes tags by
regexp matching alone (*note Etags Regexps::).

   The option `--parse-stdin=FILE' is mostly useful when calling
`etags' from programs.  It can be used (only once) in place of a file
name on the command line.  `etags' will read from standard input and
mark the produced tags as belonging to the file FILE.

   `etags --help' outputs the list of the languages `etags' knows, and
the file name rules for guessing the language.  It also prints a list
of all the available `etags' options, together with a short
explanation.  If followed by one or more `--language=LANG' options, it
outputs detailed information about how tags are generated for LANG.


File: emacs,  Node: Etags Regexps,  Next: Select Tags Table,  Prev: Create Tags Table,  Up: Tags

28.3.3 Etags Regexps
--------------------

The `--regex' option to `etags' allows tags to be recognized by regular
expression matching.  You can intermix this option with file names;
each one applies to the source files that follow it.  If you specify
multiple `--regex' options, all of them are used in parallel.  The
syntax is:

     --regex=[{LANGUAGE}]/TAGREGEXP/[NAMEREGEXP/]MODIFIERS

The essential part of the option value is TAGREGEXP, the regexp for
matching tags.  It is always used anchored, that is, it only matches at
the beginning of a line.  If you want to allow indented tags, use a
regexp that matches initial whitespace; start it with `[ \t]*'.

   In these regular expressions, `\' quotes the next character, and all
the GCC character escape sequences are supported (`\a' for bell, `\b'
for back space, `\d' for delete, `\e' for escape, `\f' for formfeed,
`\n' for newline, `\r' for carriage return, `\t' for tab, and `\v' for
vertical tab).

   Ideally, TAGREGEXP should not match more characters than are needed
to recognize what you want to tag.  If the syntax requires you to write
TAGREGEXP so it matches more characters beyond the tag itself, you
should add a NAMEREGEXP, to pick out just the tag.  This will enable
Emacs to find tags more accurately and to do completion on tag names
more reliably.  You can find some examples below.

   The MODIFIERS are a sequence of zero or more characters that modify
the way `etags' does the matching.  A regexp with no modifiers is
applied sequentially to each line of the input file, in a
case-sensitive way.  The modifiers and their meanings are:

`i'
     Ignore case when matching this regexp.

`m'
     Match this regular expression against the whole file, so that
     multi-line matches are possible.

`s'
     Match this regular expression against the whole file, and allow
     `.' in TAGREGEXP to match newlines.

   The `-R' option cancels all the regexps defined by preceding
`--regex' options.  It too applies to the file names following it.
Here's an example:

     etags --regex=/REG1/i voo.doo --regex=/REG2/m \
         bar.ber -R --lang=lisp los.er

Here `etags' chooses the parsing language for `voo.doo' and `bar.ber'
according to their contents.  `etags' also uses REG1 to recognize
additional tags in `voo.doo', and both REG1 and REG2 to recognize
additional tags in `bar.ber'.  REG1 is checked against each line of
`voo.doo' and `bar.ber', in a case-insensitive way, while REG2 is
checked against the whole `bar.ber' file, permitting multi-line
matches, in a case-sensitive way.  `etags' uses only the Lisp tags
rules, with no user-specified regexp matching, to recognize tags in
`los.er'.

   You can restrict a `--regex' option to match only files of a given
language by using the optional prefix {LANGUAGE}.  (`etags --help'
prints the list of languages recognized by `etags'.)  This is
particularly useful when storing many predefined regular expressions
for `etags' in a file.  The following example tags the `DEFVAR' macros
in the Emacs source files, for the C language only:

     --regex='{c}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/'

When you have complex regular expressions, you can store the list of
them in a file.  The following option syntax instructs `etags' to read
two files of regular expressions.  The regular expressions contained in
the second file are matched without regard to case.

     --regex=@CASE-SENSITIVE-FILE --ignore-case-regex=@IGNORE-CASE-FILE

A regex file for `etags' contains one regular expression per line.
Empty lines, and lines beginning with space or tab are ignored.  When
the first character in a line is `@', `etags' assumes that the rest of
the line is the name of another file of regular expressions; thus, one
such file can include another file.  All the other lines are taken to
be regular expressions.  If the first non-whitespace text on the line
is `--', that line is a comment.

   For example, we can create a file called `emacs.tags' with the
following contents:

             -- This is for GNU Emacs C source files
     {c}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/\1/

and then use it like this:

     etags --regex=@emacs.tags *.[ch] */*.[ch]

   Here are some more examples.  The regexps are quoted to protect them
from shell interpretation.

   * Tag Octave files:

          etags --language=none \
                --regex='/[ \t]*function.*=[ \t]*\([^ \t]*\)[ \t]*(/\1/' \
                --regex='/###key \(.*\)/\1/' \
                --regex='/[ \t]*global[ \t].*/' \
                *.m

     Note that tags are not generated for scripts, so that you have to
     add a line by yourself of the form `###key SCRIPTNAME' if you want
     to jump to it.

   * Tag Tcl files:

          etags --language=none --regex='/proc[ \t]+\([^ \t]+\)/\1/' *.tcl

   * Tag VHDL files:

          etags --language=none \
            --regex='/[ \t]*\(ARCHITECTURE\|CONFIGURATION\) +[^ ]* +OF/' \
            --regex='/[ \t]*\(ATTRIBUTE\|ENTITY\|FUNCTION\|PACKAGE\
            \( BODY\)?\|PROCEDURE\|PROCESS\|TYPE\)[ \t]+\([^ \t(]+\)/\3/'


File: emacs,  Node: Select Tags Table,  Next: Find Tag,  Prev: Etags Regexps,  Up: Tags

28.3.4 Selecting a Tags Table
-----------------------------

Emacs has at any time one "selected" tags table.  All the commands for
working with tags tables use the selected one.  To select a tags table,
type `M-x visit-tags-table', which reads the tags table file name as an
argument, with `TAGS' in the default directory as the default.

   Emacs does not actually read in the tags table contents until you
try to use them; all `visit-tags-table' does is store the file name in
the variable `tags-file-name', and setting the variable yourself is
just as good.  The variable's initial value is `nil'; that value tells
all the commands for working with tags tables that they must ask for a
tags table file name to use.

   Using `visit-tags-table' when a tags table is already loaded gives
you a choice: you can add the new tags table to the current list of
tags tables, or start a new list.  The tags commands use all the tags
tables in the current list.  If you start a new list, the new tags table
is used _instead_ of others.  If you add the new table to the current
list, it is used _as well as_ the others.

   You can specify a precise list of tags tables by setting the variable
`tags-table-list' to a list of strings, like this:

     (setq tags-table-list
           '("~/emacs" "/usr/local/lib/emacs/src"))

This tells the tags commands to look at the `TAGS' files in your
`~/emacs' directory and in the `/usr/local/lib/emacs/src' directory.
The order depends on which file you are in and which tags table
mentions that file, as explained above.

   Do not set both `tags-file-name' and `tags-table-list'.


File: emacs,  Node: Find Tag,  Next: Tags Search,  Prev: Select Tags Table,  Up: Tags

28.3.5 Finding a Tag
--------------------

The most important thing that a tags table enables you to do is to find
the definition of a specific tag.

`M-. TAG <RET>'
     Find first definition of TAG (`find-tag').

`C-u M-.'
     Find next alternate definition of last tag specified.

`C-u - M-.'
     Go back to previous tag found.

`C-M-. PATTERN <RET>'
     Find a tag whose name matches PATTERN (`find-tag-regexp').

`C-u C-M-.'
     Find the next tag whose name matches the last pattern used.

`C-x 4 . TAG <RET>'
     Find first definition of TAG, but display it in another window
     (`find-tag-other-window').

`C-x 5 . TAG <RET>'
     Find first definition of TAG, and create a new frame to select the
     buffer (`find-tag-other-frame').

`M-*'
     Pop back to where you previously invoked `M-.' and friends.

   `M-.' (`find-tag') prompts for a tag name and jumps to its source
definition.  It works by searching through the tags table for that
tag's file and approximate character position, visiting that file, and
searching for the tag definition at ever-increasing distances away from
the recorded approximate position.

   When entering the tag argument to `M-.', the usual minibuffer
completion commands can be used (*note Completion::), with the tag
names in the selected tags table as completion candidates.  If you
specify an empty argument, the balanced expression in the buffer before
or around point is the default argument.  *Note Expressions::.

   You don't need to give `M-.' the full name of the tag; a part will
do.  `M-.' finds tags which contain that argument as a substring.
However, it prefers an exact match to a substring match.  To find other
tags that match the same substring, give `find-tag' a numeric argument,
as in `C-u M-.'  or `M-0 M-.'; this does not read a tag name, but
continues searching the tags table's text for another tag containing
the same substring last used.

   Like most commands that can switch buffers, `find-tag' has a variant
that displays the new buffer in another window, and one that makes a
new frame for it.  The former is `C-x 4 .' (`find-tag-other-window'),
and the latter is `C-x 5 .' (`find-tag-other-frame').

   To move back to previous tag definitions, use `C-u - M-.'; more
generally, `M-.' with a negative numeric argument.  Similarly,
`C-x 4 .' with a negative argument finds the previous tag location in
another window.

   As well as going back to places you've found tags recently, you can
go back to places _from where_ you found them, using `M-*'
(`pop-tag-mark').  Thus you can find and examine the definition of
something with `M-.' and then return to where you were with `M-*'.

   Both `C-u - M-.' and `M-*' allow you to retrace your steps to a
depth determined by the variable `find-tag-marker-ring-length'.

   The command `C-M-.' (`find-tag-regexp') visits the tags that match a
specified regular expression.  It is just like `M-.' except that it
does regexp matching instead of substring matching.


File: emacs,  Node: Tags Search,  Next: List Tags,  Prev: Find Tag,  Up: Tags

28.3.6 Searching and Replacing with Tags Tables
-----------------------------------------------

The commands in this section visit and search all the files listed in
the selected tags table, one by one.  For these commands, the tags
table serves only to specify a sequence of files to search.  These
commands scan the list of tags tables starting with the first tags
table (if any) that describes the current file, proceed from there to
the end of the list, and then scan from the beginning of the list until
they have covered all the tables in the list.

`M-x tags-search <RET> REGEXP <RET>'
     Search for REGEXP through the files in the selected tags table.

`M-x tags-query-replace <RET> REGEXP <RET> REPLACEMENT <RET>'
     Perform a `query-replace-regexp' on each file in the selected tags
     table.

`M-,'
     Restart one of the commands above, from the current location of
     point (`tags-loop-continue').

   `M-x tags-search' reads a regexp using the minibuffer, then searches
for matches in all the files in the selected tags table, one file at a
time.  It displays the name of the file being searched so you can
follow its progress.  As soon as it finds an occurrence, `tags-search'
returns.

   Having found one match, you probably want to find all the rest.
Type `M-,' (`tags-loop-continue') to resume the `tags-search', finding
one more match.  This searches the rest of the current buffer, followed
by the remaining files of the tags table.

   `M-x tags-query-replace' performs a single `query-replace-regexp'
through all the files in the tags table.  It reads a regexp to search
for and a string to replace with, just like ordinary `M-x
query-replace-regexp'.  It searches much like `M-x tags-search', but
repeatedly, processing matches according to your input.  *Note
Replace::, for more information on query replace.

   You can control the case-sensitivity of tags search commands by
customizing the value of the variable `tags-case-fold-search'.  The
default is to use the same setting as the value of `case-fold-search'
(*note Search Case::).

   It is possible to get through all the files in the tags table with a
single invocation of `M-x tags-query-replace'.  But often it is useful
to exit temporarily, which you can do with any input event that has no
special query replace meaning.  You can resume the query replace
subsequently by typing `M-,'; this command resumes the last tags search
or replace command that you did.  For instance, to skip the rest of the
current file, you can type `M-> M-,'.

   The commands in this section carry out much broader searches than the
`find-tag' family.  The `find-tag' commands search only for definitions
of tags that match your substring or regexp.  The commands
`tags-search' and `tags-query-replace' find every occurrence of the
regexp, as ordinary search commands and replace commands do in the
current buffer.

   These commands create buffers only temporarily for the files that
they have to search (those which are not already visited in Emacs
buffers).  Buffers in which no match is found are quickly killed; the
others continue to exist.

   As an alternative to `tags-search', you can run `grep' as a
subprocess and have Emacs show you the matching lines one by one.
*Note Grep Searching::.


File: emacs,  Node: List Tags,  Prev: Tags Search,  Up: Tags

28.3.7 Tags Table Inquiries
---------------------------

`C-M-i'
`M-<TAB>'
     Perform completion on the text around point, using the selected
     tags table if one is loaded (`completion-at-point').

`M-x list-tags <RET> FILE <RET>'
     Display a list of the tags defined in the program file FILE.

`M-x tags-apropos <RET> REGEXP <RET>'
     Display a list of all tags matching REGEXP.

   In most programming language modes, you can type `C-M-i' or
`M-<TAB>' (`completion-at-point') to complete the symbol at point.  If
there is a selected tags table, this command can use it to generate
completion candidates.  *Note Symbol Completion::.

   `M-x list-tags' reads the name of one of the files covered by the
selected tags table, and displays a list of tags defined in that file.
Do not include a directory as part of the file name unless the file
name recorded in the tags table includes a directory.

   `M-x tags-apropos' is like `apropos' for tags (*note Apropos::).  It
displays a list of tags in the selected tags table whose entries match
REGEXP.  If the variable `tags-apropos-verbose' is non-`nil', it
displays the names of the tags files together with the tag names.  You
can customize the appearance of the output by setting the variable
`tags-tag-face' to a face.  You can display additional output by
customizing the variable `tags-apropos-additional-actions'; see its
documentation for details.

   `M-x next-file' visits files covered by the selected tags table.
The first time it is called, it visits the first file covered by the
table.  Each subsequent call visits the next covered file, unless a
prefix argument is supplied, in which case it returns to the first file.


File: emacs,  Node: EDE,  Next: Emerge,  Prev: Tags,  Up: Maintaining

28.4 Emacs Development Environment
==================================

EDE ("Emacs Development Environment") is a package that simplifies the
task of creating, building, and debugging large programs with Emacs.
It provides some of the features of an IDE, or "Integrated Development
Environment", in Emacs.

   This section provides a brief description of EDE usage.  For full
details, see *note EDE: (ede)Top.

   EDE is implemented as a global minor mode (*note Minor Modes::).  To
enable it, type `M-x global-ede-mode' or click on the `Project Support
(EDE)' item in the `Tools' menu.  You can also enable EDE each time you
start Emacs, by adding the following line to your initialization file:

     (global-ede-mode t)

Activating EDE adds a menu named `Development' to the menu bar.  Many
EDE commands, including the ones described below, can be invoked from
this menu.

   EDE organizes files into "projects", which correspond to directory
trees.  The "project root" is the topmost directory of a project.  To
define a new project, visit a file in the desired project root and type
`M-x ede-new'.  This command prompts for a "project type", which refers
to the underlying method that EDE will use to manage the project (*note
EDE: (ede)Creating a Project.).  The most common project types are
`Make', which uses Makefiles, and `Automake', which uses GNU Automake
(*note Automake: (automake)Top.).  In both cases, EDE also creates a
file named `Project.ede', which stores information about the project.

   A project may contain one or more "targets".  A target can be an
object file, executable program, or some other type of file, which is
"built" from one or more of the files in the project.

   To add a new "target" to a project, type `C-c . t' (`M-x
ede-new-target').  This command also asks if you wish to "add" the
current file to that target, which means that the target is to be built
from that file.  After you have defined a target, you can add more
files to it by typing `C-c . a' (`ede-add-file').

   To build a target, type `C-c . c' (`ede-compile-target').  To build
all the targets in the project, type `C-c . C' (`ede-compile-project').
EDE uses the file types to guess how the target should be built.


File: emacs,  Node: Emerge,  Prev: EDE,  Up: Maintaining

28.5 Merging Files with Emerge
==============================

It's not unusual for programmers to get their signals crossed and
modify the same program in two different directions.  To recover from
this confusion, you need to merge the two versions.  Emerge makes this
easier.  For other ways to compare files, see *note Comparing Files::,
and *note Ediff: (ediff)Top.

* Menu:

* Overview of Emerge::     How to start Emerge.  Basic concepts.
* Submodes of Emerge::     Fast mode vs. Edit mode.
                             Skip Prefers mode and Auto Advance mode.
* State of Difference::    You do the merge by specifying state A or B
                             for each difference.
* Merge Commands::         Commands for selecting a difference,
                             changing states of differences, etc.
* Exiting Emerge::         What to do when you've finished the merge.
* Combining in Emerge::    How to keep both alternatives for a difference.
* Fine Points of Emerge::  Miscellaneous issues.


File: emacs,  Node: Overview of Emerge,  Next: Submodes of Emerge,  Up: Emerge

28.5.1 Overview of Emerge
-------------------------

To start Emerge, run one of these four commands:

`M-x emerge-files'
     Merge two specified files.

`M-x emerge-files-with-ancestor'
     Merge two specified files, with reference to a common ancestor.

`M-x emerge-buffers'
     Merge two buffers.

`M-x emerge-buffers-with-ancestor'
     Merge two buffers with reference to a common ancestor in a third
     buffer.

   The Emerge commands compare two files or buffers, and display the
comparison in three buffers: one for each input text (the "A buffer"
and the "B buffer"), and one (the "merge buffer") where merging takes
place.  The merge buffer shows the full merged text, not just the
differences.  Wherever the two input texts differ, you can choose which
one of them to include in the merge buffer.

   The Emerge commands that take input from existing buffers use only
the accessible portions of those buffers, if they are narrowed.  *Note
Narrowing::.

   If a common ancestor version is available, from which the two texts
to be merged were both derived, Emerge can use it to guess which
alternative is right.  Wherever one current version agrees with the
ancestor, Emerge presumes that the other current version is a deliberate
change which should be kept in the merged version.  Use the
`with-ancestor' commands if you want to specify a common ancestor text.
These commands read three file or buffer names--variant A, variant B,
and the common ancestor.

   After the comparison is done and the buffers are prepared, the
interactive merging starts.  You control the merging by typing special
"merge commands" in the merge buffer (*note Merge Commands::).  For
each run of differences between the input texts, you can choose which
one of them to keep, or edit them both together.

   The merge buffer uses a special major mode, Emerge mode, with
commands for making these choices.  But you can also edit the buffer
with ordinary Emacs commands.

   At any given time, the attention of Emerge is focused on one
particular difference, called the "selected" difference.  This
difference is marked off in the three buffers like this:

     vvvvvvvvvvvvvvvvvvvv
     TEXT THAT DIFFERS
     ^^^^^^^^^^^^^^^^^^^^

Emerge numbers all the differences sequentially and the mode line
always shows the number of the selected difference.

   Normally, the merge buffer starts out with the A version of the text.
But when the A version of a difference agrees with the common ancestor,
then the B version is initially preferred for that difference.

   Emerge leaves the merged text in the merge buffer when you exit.  At
that point, you can save it in a file with `C-x C-w'.  If you give a
numeric argument to `emerge-files' or `emerge-files-with-ancestor', it
reads the name of the output file using the minibuffer.  (This is the
last file name those commands read.)  Then exiting from Emerge saves
the merged text in the output file.

   Normally, Emerge commands save the output buffer in its file when you
exit.  If you abort Emerge with `C-]', the Emerge command does not save
the output buffer, but you can save it yourself if you wish.


File: emacs,  Node: Submodes of Emerge,  Next: State of Difference,  Prev: Overview of Emerge,  Up: Emerge

28.5.2 Submodes of Emerge
-------------------------

You can choose between two modes for giving merge commands: Fast mode
and Edit mode.  In Fast mode, basic merge commands are single
characters, but ordinary Emacs commands are disabled.  This is
convenient if you use only merge commands.  In Edit mode, all merge
commands start with the prefix key `C-c C-c', and the normal Emacs
commands are also available.  This allows editing the merge buffer, but
slows down Emerge operations.

   Use `e' to switch to Edit mode, and `C-c C-c f' to switch to Fast
mode.  The mode line indicates Edit and Fast modes with `E' and `F'.

   Emerge has two additional submodes that affect how particular merge
commands work: Auto Advance mode and Skip Prefers mode.

   If Auto Advance mode is in effect, the `a' and `b' commands advance
to the next difference.  This lets you go through the merge faster as
long as you simply choose one of the alternatives from the input.  The
mode line indicates Auto Advance mode with `A'.

   If Skip Prefers mode is in effect, the `n' and `p' commands skip
over differences in states "prefer-A" and "prefer-B" (*note State of
Difference::).  Thus you see only differences for which neither version
is presumed "correct".  The mode line indicates Skip Prefers mode with
`S'.  This mode is only relevant when there is an ancestor.

   Use the command `s a' (`emerge-auto-advance') to set or clear Auto
Advance mode.  Use `s s' (`emerge-skip-prefers') to set or clear Skip
Prefers mode.  These commands turn on the mode with a positive
argument, turn it off with a negative or zero argument, and toggle the
mode with no argument.


File: emacs,  Node: State of Difference,  Next: Merge Commands,  Prev: Submodes of Emerge,  Up: Emerge

28.5.3 State of a Difference
----------------------------

In the merge buffer, a difference is marked with lines of `v' and `^'
characters.  Each difference has one of these seven states:

A
     The difference is showing the A version.  The `a' command always
     produces this state; the mode line indicates it with `A'.

B
     The difference is showing the B version.  The `b' command always
     produces this state; the mode line indicates it with `B'.

default-A
default-B
     The difference is showing the A or the B state by default, because
     you haven't made a choice.  All differences start in the default-A
     state (and thus the merge buffer is a copy of the A buffer),
     except those for which one alternative is "preferred" (see below).

     When you select a difference, its state changes from default-A or
     default-B to plain A or B.  Thus, the selected difference never has
     state default-A or default-B, and these states are never displayed
     in the mode line.

     The command `d a' chooses default-A as the default state, and `d
     b' chooses default-B.  This chosen default applies to all
     differences that you have never selected and for which no
     alternative is preferred.  If you are moving through the merge
     sequentially, the differences you haven't selected are those
     following the selected one.  Thus, while moving sequentially, you
     can effectively make the A version the default for some sections
     of the merge buffer and the B version the default for others by
     using `d a' and `d b' between sections.

prefer-A
prefer-B
     The difference is showing the A or B state because it is
     "preferred".  This means that you haven't made an explicit choice,
     but one alternative seems likely to be right because the other
     alternative agrees with the common ancestor.  Thus, where the A
     buffer agrees with the common ancestor, the B version is
     preferred, because chances are it is the one that was actually
     changed.

     These two states are displayed in the mode line as `A*' and `B*'.

combined
     The difference is showing a combination of the A and B states, as a
     result of the `x c' or `x C' commands.

     Once a difference is in this state, the `a' and `b' commands don't
     do anything to it unless you give them a numeric argument.

     The mode line displays this state as `comb'.


File: emacs,  Node: Merge Commands,  Next: Exiting Emerge,  Prev: State of Difference,  Up: Emerge

28.5.4 Merge Commands
---------------------

Here are the Merge commands for Fast mode; in Edit mode, precede them
with `C-c C-c':

`p'
     Select the previous difference.

`n'
     Select the next difference.

`a'
     Choose the A version of this difference.

`b'
     Choose the B version of this difference.

`C-u N j'
     Select difference number N.

`.'
     Select the difference containing point.

`q'
     Quit--finish the merge.

`C-]'
     Abort--exit merging and do not save the output.

`f'
     Go into Fast mode.  (In Edit mode, this is actually `C-c C-c f'.)

`e'
     Go into Edit mode.

`l'
     Recenter (like `C-l') all three windows.  With an argument,
     reestablish the default three-window display.

`-'
     Specify part of a prefix numeric argument.

`DIGIT'
     Also specify part of a prefix numeric argument.

`d a'
     Choose the A version as the default from here down in the merge
     buffer.

`d b'
     Choose the B version as the default from here down in the merge
     buffer.

`c a'
     Copy the A version of this difference into the kill ring.

`c b'
     Copy the B version of this difference into the kill ring.

`i a'
     Insert the A version of this difference at point.

`i b'
     Insert the B version of this difference at point.

`m'
     Put point and mark around the difference.

`^'
     Scroll all three windows down (like `M-v').

`v'
     Scroll all three windows up (like `C-v').

`<'
     Scroll all three windows left (like `C-x <').

`>'
     Scroll all three windows right (like `C-x >').

`|'
     Reset horizontal scroll on all three windows.

`x 1'
     Shrink the merge window to one line.  (Use `C-u l' to restore it
     to full size.)

`x c'
     Combine the two versions of this difference (*note Combining in
     Emerge::).

`x f'
     Show the names of the files/buffers Emerge is operating on, in a
     Help window.  (Use `C-u l' to restore windows.)

`x j'
     Join this difference with the following one.  (`C-u x j' joins
     this difference with the previous one.)

`x s'
     Split this difference into two differences.  Before you use this
     command, position point in each of the three buffers at the place
     where you want to split the difference.

`x t'
     Trim identical lines off the top and bottom of the difference.
     Such lines occur when the A and B versions are identical but
     differ from the ancestor version.


File: emacs,  Node: Exiting Emerge,  Next: Combining in Emerge,  Prev: Merge Commands,  Up: Emerge

28.5.5 Exiting Emerge
---------------------

The `q' command (`emerge-quit') finishes the merge, storing the results
into the output file if you specified one.  It restores the A and B
buffers to their proper contents, or kills them if they were created by
Emerge and you haven't changed them.  It also disables the Emerge
commands in the merge buffer, since executing them later could damage
the contents of the various buffers.

   `C-]' aborts the merge.  This means exiting without writing the
output file.  If you didn't specify an output file, then there is no
real difference between aborting and finishing the merge.

   If the Emerge command was called from another Lisp program, then its
return value is `t' for successful completion, or `nil' if you abort.


File: emacs,  Node: Combining in Emerge,  Next: Fine Points of Emerge,  Prev: Exiting Emerge,  Up: Emerge

28.5.6 Combining the Two Versions
---------------------------------

Sometimes you want to keep _both_ alternatives for a particular
difference.  To do this, use `x c', which edits the merge buffer like
this:

     #ifdef NEW
     VERSION FROM B BUFFER
     #else /* not NEW */
     VERSION FROM A BUFFER
     #endif /* not NEW */

While this example shows C preprocessor conditionals delimiting the two
alternative versions, you can specify the strings to use by setting the
variable `emerge-combine-versions-template' to a string of your choice.
In the string, `%a' says where to put version A, and `%b' says where to
put version B.  The default setting, which produces the results shown
above, looks like this:

     "#ifdef NEW\n%b#else /* not NEW */\n%a#endif /* not NEW */\n"


File: emacs,  Node: Fine Points of Emerge,  Prev: Combining in Emerge,  Up: Emerge

28.5.7 Fine Points of Emerge
----------------------------

During the merge, you mustn't try to edit the A and B buffers yourself.
Emerge modifies them temporarily, but ultimately puts them back the way
they were.

   You can have any number of merges going at once--just don't use any
one buffer as input to more than one merge at once, since the temporary
changes made in these buffers would get in each other's way.

   Starting Emerge can take a long time because it needs to compare the
files fully.  Emacs can't do anything else until `diff' finishes.
Perhaps in the future someone will change Emerge to do the comparison in
the background when the input files are large--then you could keep on
doing other things with Emacs until Emerge is ready to accept commands.

   After setting up the merge, Emerge runs the hook
`emerge-startup-hook'.  *Note Hooks::.


File: emacs,  Node: Abbrevs,  Next: Dired,  Prev: Maintaining,  Up: Top

29 Abbrevs
**********

A defined "abbrev" is a word which "expands", if you insert it, into
some different text.  Abbrevs are defined by the user to expand in
specific ways.  For example, you might define `foo' as an abbrev
expanding to `find outer otter'.  Then you could insert `find outer
otter ' into the buffer by typing `f o o <SPC>'.

   A second kind of abbreviation facility is called "dynamic abbrev
expansion".  You use dynamic abbrev expansion with an explicit command
to expand the letters in the buffer before point by looking for other
words in the buffer that start with those letters.  *Note Dynamic
Abbrevs::.

   "Hippie" expansion generalizes abbreviation expansion.  *Note Hippie
Expansion: (autotype)Hippie Expand.

* Menu:

* Abbrev Concepts::   Fundamentals of defined abbrevs.
* Defining Abbrevs::  Defining an abbrev, so it will expand when typed.
* Expanding Abbrevs:: Controlling expansion: prefixes, canceling expansion.
* Editing Abbrevs::   Viewing or editing the entire list of defined abbrevs.
* Saving Abbrevs::    Saving the entire list of abbrevs for another session.
* Dynamic Abbrevs::   Abbreviations for words already in the buffer.
* Dabbrev Customization:: What is a word, for dynamic abbrevs.  Case handling.


File: emacs,  Node: Abbrev Concepts,  Next: Defining Abbrevs,  Up: Abbrevs

29.1 Abbrev Concepts
====================

An "abbrev" is a word that has been defined to "expand" into a
specified "expansion".  When you insert a word-separator character
following the abbrev, that expands the abbrev--replacing the abbrev
with its expansion.  For example, if `foo' is defined as an abbrev
expanding to `find outer otter', then typing `f o o .' will insert
`find outer otter.'.

   Abbrevs expand only when Abbrev mode, a buffer-local minor mode, is
enabled.  Disabling Abbrev mode does not cause abbrev definitions to be
forgotten, but they do not expand until Abbrev mode is enabled again.
The command `M-x abbrev-mode' toggles Abbrev mode; with a numeric
argument, it turns Abbrev mode on if the argument is positive, off
otherwise.  *Note Minor Modes::.

   Abbrevs can have "mode-specific" definitions, active only in one
major mode.  Abbrevs can also have "global" definitions that are active
in all major modes.  The same abbrev can have a global definition and
various mode-specific definitions for different major modes.  A
mode-specific definition for the current major mode overrides a global
definition.

   You can define abbrevs interactively during the editing session,
irrespective of whether Abbrev mode is enabled.  You can also save
lists of abbrev definitions in files, which you can the reload for use
in later sessions.


File: emacs,  Node: Defining Abbrevs,  Next: Expanding Abbrevs,  Prev: Abbrev Concepts,  Up: Abbrevs

29.2 Defining Abbrevs
=====================

`C-x a g'
     Define an abbrev, using one or more words before point as its
     expansion (`add-global-abbrev').

`C-x a l'
     Similar, but define an abbrev specific to the current major mode
     (`add-mode-abbrev').

`C-x a i g'
     Define a word in the buffer as an abbrev
     (`inverse-add-global-abbrev').

`C-x a i l'
     Define a word in the buffer as a mode-specific abbrev
     (`inverse-add-mode-abbrev').

`M-x define-global-abbrev <RET> ABBREV <RET> EXP <RET>'
     Define ABBREV as an abbrev expanding into EXP.

`M-x define-mode-abbrev <RET> ABBREV <RET> EXP <RET>'
     Define ABBREV as a mode-specific abbrev expanding into EXP.

`M-x kill-all-abbrevs'
     Discard all abbrev definitions, leaving a blank slate.

   The usual way to define an abbrev is to enter the text you want the
abbrev to expand to, position point after it, and type `C-x a g'
(`add-global-abbrev').  This reads the abbrev itself using the
minibuffer, and then defines it as an abbrev for one or more words
before point.  Use a numeric argument to say how many words before
point should be taken as the expansion.  For example, to define the
abbrev `foo' as mentioned above, insert the text `find outer otter' and
then type `C-u 3 C-x a g f o o <RET>'.

   An argument of zero to `C-x a g' means to use the contents of the
region as the expansion of the abbrev being defined.

   The command `C-x a l' (`add-mode-abbrev') is similar, but defines a
mode-specific abbrev for the current major mode.  The arguments work
the same as for `C-x a g'.

   `C-x a i g' (`inverse-add-global-abbrev') and `C-x a i l'
(`inverse-add-mode-abbrev') perform the opposite task: if the abbrev
text is already in the buffer, you use these commands to define an
abbrev by specifying the expansion in the minibuffer.  These commands
will expand the abbrev text used for the definition.

   You can define an abbrev without inserting either the abbrev or its
expansion in the buffer using the command `define-global-abbrev'.  It
reads two arguments--the abbrev, and its expansion.  The command
`define-mode-abbrev' does likewise for a mode-specific abbrev.

   To change the definition of an abbrev, just make a new definition.
When an abbrev has a prior definition, the abbrev definition commands
ask for confirmation before replacing it.

   To remove an abbrev definition, give a negative argument to the
abbrev definition command: `C-u - C-x a g' or `C-u - C-x a l'.  The
former removes a global definition, while the latter removes a
mode-specific definition.  `M-x kill-all-abbrevs' removes all abbrev
definitions, both global and local.


File: emacs,  Node: Expanding Abbrevs,  Next: Editing Abbrevs,  Prev: Defining Abbrevs,  Up: Abbrevs

29.3 Controlling Abbrev Expansion
=================================

When Abbrev mode is enabled, an abbrev expands whenever it is present
in the buffer just before point and you type a self-inserting
whitespace or punctuation character (<SPC>, comma, etc.).  More
precisely, any character that is not a word constituent expands an
abbrev, and any word-constituent character can be part of an abbrev.
The most common way to use an abbrev is to insert it and then insert a
punctuation or whitespace character to expand it.

   Abbrev expansion preserves case: `foo' expands to `find outer
otter', and `Foo' to `Find outer otter'.  `FOO' expands to `Find Outer
Otter' by default, but if you change the variable `abbrev-all-caps' to
a non-`nil' value, it expands to `FIND OUTER OTTER'.

   These commands are used to control abbrev expansion:

`M-''
     Separate a prefix from a following abbrev to be expanded
     (`abbrev-prefix-mark').

`C-x a e'
     Expand the abbrev before point (`expand-abbrev').  This is
     effective even when Abbrev mode is not enabled.

`M-x expand-region-abbrevs'
     Expand some or all abbrevs found in the region.

   You may wish to expand an abbrev and attach a prefix to the
expansion; for example, if `cnst' expands into `construction', you
might want to use it to enter `reconstruction'.  It does not work to
type `recnst', because that is not necessarily a defined abbrev.  What
you can do is use the command `M-'' (`abbrev-prefix-mark') in between
the prefix `re' and the abbrev `cnst'.  First, insert `re'.  Then type
`M-''; this inserts a hyphen in the buffer to indicate that it has done
its work.  Then insert the abbrev `cnst'; the buffer now contains
`re-cnst'.  Now insert a non-word character to expand the abbrev `cnst'
into `construction'.  This expansion step also deletes the hyphen that
indicated `M-'' had been used.  The result is the desired
`reconstruction'.

   If you actually want the text of the abbrev in the buffer, rather
than its expansion, you can accomplish this by inserting the following
punctuation with `C-q'.  Thus, `foo C-q ,' leaves `foo,' in the buffer,
not expanding it.

   If you expand an abbrev by mistake, you can undo the expansion by
typing `C-/' (`undo').  *Note Undo::.  This undoes the insertion of the
abbrev expansion and brings back the abbrev text.  If the result you
want is the terminating non-word character plus the unexpanded abbrev,
you must reinsert the terminating character, quoting it with `C-q'.
You can also use the command `M-x unexpand-abbrev' to cancel the last
expansion without deleting the terminating character.

   `M-x expand-region-abbrevs' searches through the region for defined
abbrevs, and for each one found offers to replace it with its expansion.
This command is useful if you have typed in text using abbrevs but
forgot to turn on Abbrev mode first.  It may also be useful together
with a special set of abbrev definitions for making several global
replacements at once.  This command is effective even if Abbrev mode is
not enabled.

   Expanding any abbrev runs `abbrev-expand-functions', a special hook.
Functions in this special hook can make arbitrary changes to the abbrev
expansion.  *Note Abbrev Expansion: (elisp)Abbrev Expansion.


File: emacs,  Node: Editing Abbrevs,  Next: Saving Abbrevs,  Prev: Expanding Abbrevs,  Up: Abbrevs

29.4 Examining and Editing Abbrevs
==================================

`M-x list-abbrevs'
     Display a list of all abbrev definitions.  With a numeric
     argument, list only local abbrevs.

`M-x edit-abbrevs'
     Edit a list of abbrevs; you can add, alter or remove definitions.

   The output from `M-x list-abbrevs' looks like this:

     VARIOUS OTHER TABLES...
     (lisp-mode-abbrev-table)
     "dk"          0    "define-key"
     (global-abbrev-table)
     "dfn"         0    "definition"

(Some blank lines of no semantic significance, and some other abbrev
tables, have been omitted.)

   A line containing a name in parentheses is the header for abbrevs in
a particular abbrev table; `global-abbrev-table' contains all the global
abbrevs, and the other abbrev tables that are named after major modes
contain the mode-specific abbrevs.

   Within each abbrev table, each nonblank line defines one abbrev.  The
word at the beginning of the line is the abbrev.  The number that
follows is the number of times the abbrev has been expanded.  Emacs
keeps track of this to help you see which abbrevs you actually use, so
that you can eliminate those that you don't use often.  The string at
the end of the line is the expansion.

   Some abbrevs are marked with `(sys)'.  These "system" abbrevs (*note
Abbrevs: (elisp)Abbrevs.) are pre-defined by various modes, and are not
saved to your abbrev file.  To disable a "system" abbrev, define an
abbrev of the same name that expands to itself, and save it to your
abbrev file.

   `M-x edit-abbrevs' allows you to add, change or kill abbrev
definitions by editing a list of them in an Emacs buffer.  The list has
the same format described above.  The buffer of abbrevs is called
`*Abbrevs*', and is in Edit-Abbrevs mode.  Type `C-c C-c' in this
buffer to install the abbrev definitions as specified in the
buffer--and delete any abbrev definitions not listed.

   The command `edit-abbrevs' is actually the same as `list-abbrevs'
except that it selects the buffer `*Abbrevs*' whereas `list-abbrevs'
merely displays it in another window.


File: emacs,  Node: Saving Abbrevs,  Next: Dynamic Abbrevs,  Prev: Editing Abbrevs,  Up: Abbrevs

29.5 Saving Abbrevs
===================

These commands allow you to keep abbrev definitions between editing
sessions.

`M-x write-abbrev-file <RET> FILE <RET>'
     Write a file FILE describing all defined abbrevs.

`M-x read-abbrev-file <RET> FILE <RET>'
     Read the file FILE and define abbrevs as specified therein.

`M-x define-abbrevs'
     Define abbrevs from definitions in current buffer.

`M-x insert-abbrevs'
     Insert all abbrevs and their expansions into current buffer.

   `M-x write-abbrev-file' reads a file name using the minibuffer and
then writes a description of all current abbrev definitions into that
file.  This is used to save abbrev definitions for use in a later
session.  The text stored in the file is a series of Lisp expressions
that, when executed, define the same abbrevs that you currently have.

   `M-x read-abbrev-file' reads a file name using the minibuffer and
then reads the file, defining abbrevs according to the contents of the
file.  The function `quietly-read-abbrev-file' is similar except that
it does not display a message in the echo area; you cannot invoke it
interactively, and it is used primarily in your init file (*note Init
File::).  If either of these functions is called with `nil' as the
argument, it uses the file given by the variable `abbrev-file-name',
which is `~/.emacs.d/abbrev_defs' by default.  This is your standard
abbrev definition file, and Emacs loads abbrevs from it automatically
when it starts up.  (As an exception, Emacs does not load the abbrev
file when it is started in batch mode.  *Note Initial Options::, for a
description of batch mode.)

   Emacs will offer to save abbrevs automatically if you have changed
any of them, whenever it offers to save all files (for `C-x s' or `C-x
C-c').  It saves them in the file specified by `abbrev-file-name'.
This feature can be inhibited by setting the variable `save-abbrevs' to
`nil'.

   The commands `M-x insert-abbrevs' and `M-x define-abbrevs' are
similar to the previous commands but work on text in an Emacs buffer.
`M-x insert-abbrevs' inserts text into the current buffer after point,
describing all current abbrev definitions; `M-x define-abbrevs' parses
the entire current buffer and defines abbrevs accordingly.


File: emacs,  Node: Dynamic Abbrevs,  Next: Dabbrev Customization,  Prev: Saving Abbrevs,  Up: Abbrevs

29.6 Dynamic Abbrev Expansion
=============================

The abbrev facility described above operates automatically as you
insert text, but all abbrevs must be defined explicitly.  By contrast,
"dynamic abbrevs" allow the meanings of abbreviations to be determined
automatically from the contents of the buffer, but dynamic abbrev
expansion happens only when you request it explicitly.

`M-/'
     Expand the word in the buffer before point as a "dynamic abbrev",
     by searching in the buffer for words starting with that
     abbreviation (`dabbrev-expand').

`C-M-/'
     Complete the word before point as a dynamic abbrev
     (`dabbrev-completion').

   For example, if the buffer contains `does this follow ' and you type
`f o M-/', the effect is to insert `follow' because that is the last
word in the buffer that starts with `fo'.  A numeric argument to `M-/'
says to take the second, third, etc. distinct expansion found looking
backward from point.  Repeating `M-/' searches for an alternative
expansion by looking farther back.  After scanning all the text before
point, it searches the text after point.  The variable `dabbrev-limit',
if non-`nil', specifies how far away in the buffer to search for an
expansion.

   After scanning the current buffer, `M-/' normally searches other
buffers, unless you have set `dabbrev-check-all-buffers' to `nil'.

   For finer control over which buffers to scan, customize the variable
`dabbrev-ignored-buffer-regexps'.  Its value is a list of regular
expressions.  If a buffer's name matches any of these regular
expressions, dynamic abbrev expansion skips that buffer.

   A negative argument to `M-/', as in `C-u - M-/', says to search
first for expansions after point, then other buffers, and consider
expansions before point only as a last resort.  If you repeat the `M-/'
to look for another expansion, do not specify an argument.  Repeating
`M-/' cycles through all the expansions after point and then the
expansions before point.

   After you have expanded a dynamic abbrev, you can copy additional
words that follow the expansion in its original context.  Simply type
`<SPC> M-/' for each additional word you want to copy.  The spacing and
punctuation between words is copied along with the words.

   The command `C-M-/' (`dabbrev-completion') performs completion of a
dynamic abbrev.  Instead of trying the possible expansions one by one,
it finds all of them, then inserts the text that they have in common.
If they have nothing in common, `C-M-/' displays a list of completions,
from which you can select a choice in the usual manner.  *Note
Completion::.

   Dynamic abbrev expansion is completely independent of Abbrev mode;
the expansion of a word with `M-/' is completely independent of whether
it has a definition as an ordinary abbrev.


File: emacs,  Node: Dabbrev Customization,  Prev: Dynamic Abbrevs,  Up: Abbrevs

29.7 Customizing Dynamic Abbreviation
=====================================

Normally, dynamic abbrev expansion ignores case when searching for
expansions.  That is, the expansion need not agree in case with the word
you are expanding.

   This feature is controlled by the variable
`dabbrev-case-fold-search'.  If it is `t', case is ignored in this
search; if it is `nil', the word and the expansion must match in case.
If the value is `case-fold-search' (the default), then the variable
`case-fold-search' controls whether to ignore case while searching for
expansions (*note Search Case::).

   Normally, dynamic abbrev expansion preserves the case pattern _of
the dynamic abbrev you are expanding_, by converting the expansion to
that case pattern.

   The variable `dabbrev-case-replace' controls whether to preserve the
case pattern of the dynamic abbrev.  If it is `t', the dynamic abbrev's
case pattern is preserved in most cases; if it is `nil', the expansion
is always copied verbatim.  If the value is `case-replace' (the
default), then the variable `case-replace' controls whether to copy the
expansion verbatim (*note Replacement and Case::).

   However, if the expansion contains a complex mixed case pattern, and
the dynamic abbrev matches this pattern as far as it goes, then the
expansion is always copied verbatim, regardless of those variables.
Thus, for example, if the buffer contains
`variableWithSillyCasePattern', and you type `v a M-/', it copies the
expansion verbatim including its case pattern.

   The variable `dabbrev-abbrev-char-regexp', if non-`nil', controls
which characters are considered part of a word, for dynamic expansion
purposes.  The regular expression must match just one character, never
two or more.  The same regular expression also determines which
characters are part of an expansion.  The value `nil' has a special
meaning: dynamic abbrevs are made of word characters, but expansions are
made of word and symbol characters.

   In shell scripts and makefiles, a variable name is sometimes prefixed
with `$' and sometimes not.  Major modes for this kind of text can
customize dynamic abbrev expansion to handle optional prefixes by
setting the variable `dabbrev-abbrev-skip-leading-regexp'.  Its value
should be a regular expression that matches the optional prefix that
dynamic abbrev expression should ignore.


File: emacs,  Node: Dired,  Next: Calendar/Diary,  Prev: Abbrevs,  Up: Top

30 Dired, the Directory Editor
******************************

Dired makes an Emacs buffer containing a listing of a directory, and
optionally some of its subdirectories as well.  You can use the normal
Emacs commands to move around in this buffer, and special Dired
commands to operate on the listed files.

   The Dired buffer is "read-only", and inserting text in it is not
allowed.  Ordinary printing characters such as `d' and `x' are
redefined for special Dired commands.  Some Dired commands "mark" or
"flag" the "current file" (that is, the file on the current line);
other commands operate on the marked files or on the flagged files.
You first mark certain files in order to operate on all of them with
one command.

   The Dired-X package provides various extra features for Dired mode.
*Note Dired-X: (dired-x)Top.

   You can also view a list of files in a directory with `C-x C-d'
(`list-directory').  Unlike Dired, this command does not allow you to
operate on the listed files.  *Note Directories::.

* Menu:

* Enter: Dired Enter.         How to invoke Dired.
* Navigation: Dired Navigation.   Special motion commands in the Dired buffer.
* Deletion: Dired Deletion.   Deleting files with Dired.
* Flagging Many Files::       Flagging files based on their names.
* Visit: Dired Visiting.      Other file operations through Dired.
* Marks vs Flags::            Flagging for deletion vs marking.
* Operating on Files::        How to copy, rename, print, compress, etc.
                                either one file or several files.
* Shell Commands in Dired::   Running a shell command on the marked files.
* Transforming File Names::   Using patterns to rename multiple files.
* Comparison in Dired::       Running `diff' by way of Dired.
* Subdirectories in Dired::   Adding subdirectories to the Dired buffer.

* Subdir Switches::           Subdirectory switches in Dired.
* Subdirectory Motion::       Moving across subdirectories, and up and down.
* Hiding Subdirectories::     Making subdirectories visible or invisible.
* Updating: Dired Updating.   Discarding lines for files of no interest.
* Find: Dired and Find.       Using `find' to choose the files for Dired.
* Wdired::                    Operating on files by editing the Dired buffer.
* Image-Dired::               Viewing image thumbnails in Dired.
* Misc: Misc Dired Features.  Various other features.


File: emacs,  Node: Dired Enter,  Next: Dired Navigation,  Up: Dired

30.1 Entering Dired
===================

To invoke Dired, type `C-x d' (`dired').  This reads a directory name
using the minibuffer, and opens a "Dired buffer" listing the files in
that directory.  You can also supply a wildcard file name pattern as
the minibuffer argument, in which case the Dired buffer lists all files
matching that pattern.  The usual history and completion commands can
be used in the minibuffer; in particular, `M-n' puts the name of the
visited file (if any) in the minibuffer (*note Minibuffer History::).

   You can also invoke Dired by giving `C-x C-f' (`find-file') a
directory name.

   The variable `dired-listing-switches' specifies the options to give
to `ls' for listing the directory; this string _must_ contain `-l'.  If
you use a prefix argument with the `dired' command, you can specify the
`ls' switches with the minibuffer before you enter the directory
specification.  No matter how they are specified, the `ls' switches can
include short options (that is, single characters) requiring no
arguments, and long options (starting with `--') whose arguments are
specified with `='.

   If your `ls' program supports the `--dired' option, Dired
automatically passes it that option; this causes `ls' to emit special
escape sequences for certain unusual file names, without which Dired
will not be able to parse those names.  The first time you run Dired in
an Emacs session, it checks whether `ls' supports the `--dired' option
by calling it once with that option.  If the exit code is 0, Dired will
subsequently use the `--dired' option; otherwise it will not.  You can
inhibit this check by customizing the variable `dired-use-ls-dired'.
The value `unspecified' (the default) means to perform the check; any
other non-`nil' value means to use the `--dired' option; and `nil'
means not to use the `--dired' option.

   On MS-Windows and MS-DOS systems, Emacs emulates `ls'.  *Note ls in
Lisp::, for options and peculiarities of this emulation.

   To display the Dired buffer in another window, use `C-x 4 d'
(`dired-other-window').  `C-x 5 d' (`dired-other-frame') displays the
Dired buffer in a separate frame.

   Typing `q' (`quit-window') buries the Dired buffer, and deletes its
window if the window was created just for that buffer.


File: emacs,  Node: Dired Navigation,  Next: Dired Deletion,  Prev: Dired Enter,  Up: Dired

30.2 Navigation in the Dired Buffer
===================================

All the usual Emacs cursor motion commands are available in Dired
buffers.  The keys `C-n' and `C-p' are redefined to put the cursor at
the beginning of the file name on the line, rather than at the
beginning of the line.

   For extra convenience, <SPC> and `n' in Dired are equivalent to
`C-n'.  `p' is equivalent to `C-p'.  (Moving by lines is so common in
Dired that it deserves to be easy to type.)  <DEL> (move up and unflag)
is also often useful simply for moving up (*note Dired Deletion::).

   `j' (`dired-goto-file') prompts for a file name using the
minibuffer, and moves point to the line in the Dired buffer describing
that file.

   `M-s f C-s' (`dired-isearch-filenames') performs a forward
incremental search in the Dired buffer, looking for matches only
amongst the file names and ignoring the rest of the text in the buffer.
`M-s f M-C-s' (`dired-isearch-filenames-regexp') does the same, using a
regular expression search.  If you change the variable
`dired-isearch-filenames' to `t', then the usual search commands also
limit themselves to the file names; for instance, `C-s' behaves like
`M-s f C-s'.  If the value is `dwim', then search commands match the
file names only when point was on a file name initially.  *Note
Search::, for information about incremental search.

   Some additional navigation commands are available when the Dired
buffer includes several directories.  *Note Subdirectory Motion::.


File: emacs,  Node: Dired Deletion,  Next: Flagging Many Files,  Prev: Dired Navigation,  Up: Dired

30.3 Deleting Files with Dired
==============================

One of the most frequent uses of Dired is to first "flag" files for
deletion, then delete the files that were flagged.

`d'
     Flag this file for deletion.

`u'
     Remove deletion flag on this line.

`<DEL>'
     Move point to previous line and remove the deletion flag on that
     line.

`x'
     Delete the files that are flagged for deletion.

   You can flag a file for deletion by moving to the line describing
the file and typing `d' (`dired-flag-file-deletion').  The deletion
flag is visible as a `D' at the beginning of the line.  This command
moves point to the next line, so that repeated `d' commands flag
successive files.  A numeric argument serves as a repeat count.

   The reason for flagging files for deletion, rather than deleting
files immediately, is to reduce the danger of deleting a file
accidentally.  Until you direct Dired to delete the flagged files, you
can remove deletion flags using the commands `u' and <DEL>.  `u'
(`dired-unmark') works just like `d', but removes flags rather than
making flags.  <DEL> (`dired-unmark-backward') moves upward, removing
flags; it is like `u' with argument -1.

   To delete the flagged files, type `x' (`dired-do-flagged-delete').
This command first displays a list of all the file names flagged for
deletion, and requests confirmation with `yes'.  If you confirm, Dired
deletes the flagged files, then deletes their lines from the text of
the Dired buffer.  The Dired buffer, with somewhat fewer lines, remains
selected.

   If you answer `no' or quit with `C-g' when asked to confirm, you
return immediately to Dired, with the deletion flags still present in
the buffer, and no files actually deleted.

   You can delete empty directories just like other files, but normally
Dired cannot delete directories that are nonempty.  If the variable
`dired-recursive-deletes' is non-`nil', then Dired can delete nonempty
directories including all their contents.  That can be somewhat risky.

   If you change the variable `delete-by-moving-to-trash' to `t', the
above deletion commands will move the affected files or directories
into the operating system's Trash, instead of deleting them outright.
*Note Misc File Ops::.


File: emacs,  Node: Flagging Many Files,  Next: Dired Visiting,  Prev: Dired Deletion,  Up: Dired

30.4 Flagging Many Files at Once
================================

The `#', `~', `.', `% &', and `% d' commands flag many files for
deletion, based on their file names:

`#'
     Flag all auto-save files (files whose names start and end with `#')
     for deletion (*note Auto Save::).

`~'
     Flag all backup files (files whose names end with `~') for deletion
     (*note Backup::).

`. (Period)'
     Flag excess numeric backup files for deletion.  The oldest and
     newest few backup files of any one file are exempt; the middle
     ones are flagged.

`% &'
     Flag for deletion all files with certain kinds of names which
     suggest you could easily create those files again.

`% d REGEXP <RET>'
     Flag for deletion all files whose names match the regular
     expression REGEXP.

   `#' (`dired-flag-auto-save-files') flags all files whose names look
like auto-save files--that is, files whose names begin and end with
`#'.  *Note Auto Save::.

   `~' (`dired-flag-backup-files') flags all files whose names say they
are backup files--that is, files whose names end in `~'.  *Note
Backup::.

   `.' (period, `dired-clean-directory') flags just some of the backup
files for deletion: all but the oldest few and newest few backups of
any one file.  Normally, the number of newest versions kept for each
file is given by the variable `dired-kept-versions' (*not*
`kept-new-versions'; that applies only when saving).  The number of
oldest versions to keep is given by the variable `kept-old-versions'.

   Period with a positive numeric argument, as in `C-u 3 .', specifies
the number of newest versions to keep, overriding
`dired-kept-versions'.  A negative numeric argument overrides
`kept-old-versions', using minus the value of the argument to specify
the number of oldest versions of each file to keep.

   `% &' (`dired-flag-garbage-files') flags files whose names match the
regular expression specified by the variable
`dired-garbage-files-regexp'.  By default, this matches certain files
produced by TeX, `.bak' files, and the `.orig' and `.rej' files
produced by `patch'.

   `% d' flags all files whose names match a specified regular
expression (`dired-flag-files-regexp').  Only the non-directory part of
the file name is used in matching.  You can use `^' and `$' to anchor
matches.  You can exclude certain subdirectories from marking by hiding
them while you use `% d'.  *Note Hiding Subdirectories::.


File: emacs,  Node: Dired Visiting,  Next: Marks vs Flags,  Prev: Flagging Many Files,  Up: Dired

30.5 Visiting Files in Dired
============================

There are several Dired commands for visiting or examining the files
listed in the Dired buffer.  All of them apply to the current line's
file; if that file is really a directory, these commands invoke Dired on
that subdirectory (making a separate Dired buffer).

`f'
     Visit the file described on the current line, like typing `C-x C-f'
     and supplying that file name (`dired-find-file').  *Note
     Visiting::.

`<RET>'
`e'
     Equivalent to `f'.

`o'
     Like `f', but uses another window to display the file's buffer
     (`dired-find-file-other-window').  The Dired buffer remains visible
     in the first window.  This is like using `C-x 4 C-f' to visit the
     file.  *Note Windows::.

`C-o'
     Visit the file described on the current line, and display the
     buffer in another window, but do not select that window
     (`dired-display-file').

`Mouse-1'
`Mouse-2'
     Visit the file whose name you clicked on
     (`dired-mouse-find-file-other-window').  This uses another window
     to display the file, like the `o' command.

`v'
     View the file described on the current line, with View mode
     (`dired-view-file').  View mode provides convenient commands to
     navigate the buffer but forbids changing it; *Note View Mode::.

`^'
     Visit the parent directory of the current directory
     (`dired-up-directory').  This is equivalent to moving to the line
     for `..' and typing `f' there.


File: emacs,  Node: Marks vs Flags,  Next: Operating on Files,  Prev: Dired Visiting,  Up: Dired

30.6 Dired Marks vs. Flags
==========================

Instead of flagging a file with `D', you can "mark" the file with some
other character (usually `*').  Most Dired commands to operate on files
use the files marked with `*'.  The only command that operates on
flagged files is `x', which deletes them.

   Here are some commands for marking with `*', for unmarking, and for
operating on marks.  (*Note Dired Deletion::, for commands to flag and
unflag files.)

`m'
`* m'
     Mark the current file with `*' (`dired-mark').  With a numeric
     argument N, mark the next N files starting with the current file.
     (If N is negative, mark the previous -N files.)

`* *'
     Mark all executable files with `*' (`dired-mark-executables').
     With a numeric argument, unmark all those files.

`* @'
     Mark all symbolic links with `*' (`dired-mark-symlinks').  With a
     numeric argument, unmark all those files.

`* /'
     Mark with `*' all files which are directories, except for `.' and
     `..' (`dired-mark-directories').  With a numeric argument, unmark
     all those files.

`* s'
     Mark all the files in the current subdirectory, aside from `.' and
     `..' (`dired-mark-subdir-files').

`u'
`* u'
     Remove any mark on this line (`dired-unmark').

`<DEL>'
`* <DEL>'
     Move point to previous line and remove any mark on that line
     (`dired-unmark-backward').

`* !'
`U'
     Remove all marks from all the files in this Dired buffer
     (`dired-unmark-all-marks').

`* ? MARKCHAR'
`M-<DEL>'
     Remove all marks that use the character MARKCHAR
     (`dired-unmark-all-files').  The argument is a single
     character--do not use <RET> to terminate it.  See the description
     of the `* c' command below, which lets you replace one mark
     character with another.

     With a numeric argument, this command queries about each marked
     file, asking whether to remove its mark.  You can answer `y'
     meaning yes, `n' meaning no, or `!' to remove the marks from the
     remaining files without asking about them.

`* C-n'
`M-}'
     Move down to the next marked file (`dired-next-marked-file') A
     file is "marked" if it has any kind of mark.

`* C-p'
`M-{'
     Move up to the previous marked file (`dired-prev-marked-file')

`t'
`* t'
     Toggle all marks (`dired-toggle-marks'): files marked with `*'
     become unmarked, and unmarked files are marked with `*'.  Files
     marked in any other way are not affected.

`* c OLD-MARKCHAR NEW-MARKCHAR'
     Replace all marks that use the character OLD-MARKCHAR with marks
     that use the character NEW-MARKCHAR (`dired-change-marks').  This
     command is the primary way to create or use marks other than `*'
     or `D'.  The arguments are single characters--do not use <RET> to
     terminate them.

     You can use almost any character as a mark character by means of
     this command, to distinguish various classes of files.  If
     OLD-MARKCHAR is a space (` '), then the command operates on all
     unmarked files; if NEW-MARKCHAR is a space, then the command
     unmarks the files it acts on.

     To illustrate the power of this command, here is how to put `D'
     flags on all the files that have no marks, while unflagging all
     those that already have `D' flags:

          * c D t  * c SPC D  * c t SPC

     This assumes that no files were already marked with `t'.

`% m REGEXP <RET>'
`* % REGEXP <RET>'
     Mark (with `*') all files whose names match the regular expression
     REGEXP (`dired-mark-files-regexp').  This command is like `% d',
     except that it marks files with `*' instead of flagging with `D'.

     Only the non-directory part of the file name is used in matching.
     Use `^' and `$' to anchor matches.  You can exclude subdirectories
     by temporarily hiding them (*note Hiding Subdirectories::).

`% g REGEXP <RET>'
     Mark (with `*') all files whose _contents_ contain a match for the
     regular expression REGEXP (`dired-mark-files-containing-regexp').
     This command is like `% m', except that it searches the file
     contents instead of the file name.

`C-/'
`C-x u'
`C-_'
     Undo changes in the Dired buffer, such as adding or removing marks
     (`dired-undo').  _This command does not revert the actual file
     operations, nor recover lost files!_  It just undoes changes in
     the buffer itself.

     In some cases, using this after commands that operate on files can
     cause trouble.  For example, after renaming one or more files,
     `dired-undo' restores the original names in the Dired buffer,
     which gets the Dired buffer out of sync with the actual contents of
     the directory.


File: emacs,  Node: Operating on Files,  Next: Shell Commands in Dired,  Prev: Marks vs Flags,  Up: Dired

30.7 Operating on Files
=======================

This section describes the basic Dired commands to operate on one file
or several files.  All of these commands are capital letters; all of
them use the minibuffer, either to read an argument or to ask for
confirmation, before they act.  All of them let you specify the files
to manipulate in these ways:

   * If you give the command a numeric prefix argument N, it operates
     on the next N files, starting with the current file.  (If N is
     negative, the command operates on the -N files preceding the
     current line.)

   * Otherwise, if some files are marked with `*', the command operates
     on all those files.

   * Otherwise, the command operates on the current file only.

Certain other Dired commands, such as `!' and the `%' commands, use the
same conventions to decide which files to work on.

   Commands which ask for a destination directory, such as those which
copy and rename files or create links for them, try to guess the default
target directory for the operation.  Normally, they suggest the Dired
buffer's default directory, but if the variable `dired-dwim-target' is
non-`nil', and if there is another Dired buffer displayed in the next
window, that other buffer's directory is suggested instead.

   Here are the file-manipulating Dired commands that operate on files.

`C NEW <RET>'
     Copy the specified files (`dired-do-copy').  The argument NEW is
     the directory to copy into, or (if copying a single file) the new
     name.  This is like the shell command `cp'.

     If `dired-copy-preserve-time' is non-`nil', then copying with this
     command preserves the modification time of the old file in the
     copy, like `cp -p'.

     The variable `dired-recursive-copies' controls whether to copy
     directories recursively (like `cp -r').  The default is `top',
     which means to ask before recursively copying a directory.

`D'
     Delete the specified files (`dired-do-delete').  This is like the
     shell command `rm'.

     Like the other commands in this section, this command operates on
     the _marked_ files, or the next N files.  By contrast, `x'
     (`dired-do-flagged-delete') deletes all "flagged" files.

`R NEW <RET>'
     Rename the specified files (`dired-do-rename').  If you rename a
     single file, the argument NEW is the new name of the file.  If you
     rename several files, the argument NEW is the directory into which
     to move the files (this is like the shell command `mv').

     Dired automatically changes the visited file name of buffers
     associated with renamed files so that they refer to the new names.

`H NEW <RET>'
     Make hard links to the specified files (`dired-do-hardlink').
     This is like the shell command `ln'.  The argument NEW is the
     directory to make the links in, or (if making just one link) the
     name to give the link.

`S NEW <RET>'
     Make symbolic links to the specified files (`dired-do-symlink').
     This is like `ln -s'.  The argument NEW is the directory to make
     the links in, or (if making just one link) the name to give the
     link.

`M MODESPEC <RET>'
     Change the mode (also called "permission bits") of the specified
     files (`dired-do-chmod').  MODESPEC can be in octal or symbolic
     notation, like arguments handled by the `chmod' program.

`G NEWGROUP <RET>'
     Change the group of the specified files to NEWGROUP
     (`dired-do-chgrp').

`O NEWOWNER <RET>'
     Change the owner of the specified files to NEWOWNER
     (`dired-do-chown').  (On most systems, only the superuser can do
     this.)

     The variable `dired-chown-program' specifies the name of the
     program to use to do the work (different systems put `chown' in
     different places).

`T TIMESTAMP <RET>'
     Touch the specified files (`dired-do-touch').  This means updating
     their modification times to the present time.  This is like the
     shell command `touch'.

`P COMMAND <RET>'
     Print the specified files (`dired-do-print').  You must specify the
     command to print them with, but the minibuffer starts out with a
     suitable guess made using the variables `lpr-command' and
     `lpr-switches' (the same variables that `lpr-buffer' uses; *note
     Printing::).

`Z'
     Compress the specified files (`dired-do-compress').  If the file
     appears to be a compressed file already, uncompress it instead.

`:d'
     Decrypt the specified files (`epa-dired-do-decrypt').  *Note Dired
     integration: (epa)Dired integration.

`:v'
     Verify digital signatures on the specified files
     (`epa-dired-do-verify').  *Note Dired integration: (epa)Dired
     integration.

`:s'
     Digitally sign the specified files (`epa-dired-do-sign').  *Note
     Dired integration: (epa)Dired integration.

`:e'
     Encrypt the specified files (`epa-dired-do-encrypt').  *Note Dired
     integration: (epa)Dired integration.

`L'
     Load the specified Emacs Lisp files (`dired-do-load').  *Note Lisp
     Libraries::.

`B'
     Byte compile the specified Emacs Lisp files
     (`dired-do-byte-compile').  *Note Byte Compilation: (elisp)Byte
     Compilation.

`A REGEXP <RET>'
     Search all the specified files for the regular expression REGEXP
     (`dired-do-search').

     This command is a variant of `tags-search'.  The search stops at
     the first match it finds; use `M-,' to resume the search and find
     the next match.  *Note Tags Search::.

`Q REGEXP <RET> TO <RET>'
     Perform `query-replace-regexp' on each of the specified files,
     replacing matches for REGEXP with the string TO
     (`dired-do-query-replace-regexp').

     This command is a variant of `tags-query-replace'.  If you exit the
     query replace loop, you can use `M-,' to resume the scan and
     replace more matches.  *Note Tags Search::.


File: emacs,  Node: Shell Commands in Dired,  Next: Transforming File Names,  Prev: Operating on Files,  Up: Dired

30.8 Shell Commands in Dired
============================

The Dired command `!' (`dired-do-shell-command') reads a shell command
string in the minibuffer and runs that shell command on one or more
files.  The files that the shell command operates on are determined in
the usual way for Dired commands (*note Operating on Files::).  The
command `X' is a synonym for `!'.

   The command `&' (`dired-do-async-shell-command') does the same,
except that it runs the shell command asynchronously.  You can also do
this with `!', by appending a `&' character to the end of the shell
command.

   For both `!' and `&', the working directory for the shell command is
the top-level directory of the Dired buffer.

   If you tell `!' or `&' to operate on more than one file, the shell
command string determines how those files are passed to the shell
command:

   * If you use `*' surrounded by whitespace in the command string,
     then the command runs just once, with the list of file names
     substituted for the `*'.  The order of file names is the order of
     appearance in the Dired buffer.

     Thus, `! tar cf foo.tar * <RET>' runs `tar' on the entire list of
     file names, putting them into one tar file `foo.tar'.

     If you want to use `*' as a shell wildcard with whitespace around
     it, write `*""'.  In the shell, this is equivalent to `*'; but
     since the `*' is not surrounded by whitespace, Dired does not
     treat it specially.

   * Otherwise, if the command string contains `?' surrounded by
     whitespace, Emacs runs the shell command once _for each file_,
     substituting the current file name for `?' each time.  You can use
     `?' more than once in the command; the same file name replaces
     each occurrence.

   * If the command string contains neither `*' nor `?', Emacs runs the
     shell command once for each file, adding the file name at the end.
     For example, `! uudecode <RET>' runs `uudecode' on each file.

   To iterate over the file names in a more complicated fashion, use an
explicit shell loop.  For example, here is how to uuencode each file,
making the output file name by appending `.uu' to the input file name:

     for file in * ; do uuencode "$file" "$file" >"$file".uu; done

   The `!' and `&' commands do not attempt to update the Dired buffer
to show new or modified files, because they don't know what files will
be changed.  Use the `g' command to update the Dired buffer (*note
Dired Updating::).

   *Note Single Shell::, for information about running shell commands
outside Dired.


File: emacs,  Node: Transforming File Names,  Next: Comparison in Dired,  Prev: Shell Commands in Dired,  Up: Dired

30.9 Transforming File Names in Dired
=====================================

This section describes Dired commands which alter file names in a
systematic way.  Each command operates on some or all of the marked
files, using a new name made by transforming the existing name.

   Like the basic Dired file-manipulation commands (*note Operating on
Files::), the commands described here operate either on the next N
files, or on all files marked with `*', or on the current file.  (To
mark files, use the commands described in *note Marks vs Flags::.)

   All of the commands described in this section work _interactively_:
they ask you to confirm the operation for each candidate file.  Thus,
you can select more files than you actually need to operate on (e.g.,
with a regexp that matches many files), and then filter the selected
names by typing `y' or `n' when the command prompts for confirmation.

`% u'
     Rename each of the selected files to an upper-case name
     (`dired-upcase').  If the old file names are `Foo' and `bar', the
     new names are `FOO' and `BAR'.

`% l'
     Rename each of the selected files to a lower-case name
     (`dired-downcase').  If the old file names are `Foo' and `bar',
     the new names are `foo' and `bar'.

`% R FROM <RET> TO <RET>'
`% C FROM <RET> TO <RET>'
`% H FROM <RET> TO <RET>'
`% S FROM <RET> TO <RET>'
     These four commands rename, copy, make hard links and make soft
     links, in each case computing the new name by regular-expression
     substitution from the name of the old file.

   The four regular-expression substitution commands effectively
perform a search-and-replace on the selected file names.  They read two
arguments: a regular expression FROM, and a substitution pattern TO;
they match each "old" file name against FROM, and then replace the
matching part with TO.  You can use `\&' and `\DIGIT' in TO to refer to
all or part of what the pattern matched in the old file name, as in
`replace-regexp' (*note Regexp Replace::).  If the regular expression
matches more than once in a file name, only the first match is replaced.

   For example, `% R ^.*$ <RET> x-\& <RET>' renames each selected file
by prepending `x-' to its name.  The inverse of this, removing `x-'
from the front of each file name, is also possible: one method is `% R
^x-\(.*\)$ <RET> \1 <RET>'; another is `% R ^x- <RET> <RET>'.  (Use `^'
and `$' to anchor matches that should span the whole file name.)

   Normally, the replacement process does not consider the files'
directory names; it operates on the file name within the directory.  If
you specify a numeric argument of zero, then replacement affects the
entire absolute file name including directory name.  (A non-zero
argument specifies the number of files to operate on.)

   You may want to select the set of files to operate on using the same
regexp FROM that you will use to operate on them.  To do this, mark
those files with `% m FROM <RET>', then use the same regular expression
in the command to operate on the files.  To make this more convenient,
the `%' commands to operate on files use the last regular expression
specified in any `%' command as a default.


File: emacs,  Node: Comparison in Dired,  Next: Subdirectories in Dired,  Prev: Transforming File Names,  Up: Dired

30.10 File Comparison with Dired
================================

Here are two Dired commands that compare specified files using `diff'.
They show the output in a buffer using Diff mode (*note Comparing
Files::).

`='
     Compare the current file (the file at point) with another file (the
     file at the mark) using the `diff' program (`dired-diff').  The
     file at the mark is the first argument of `diff', and the file at
     point is the second argument.  This refers to the ordinary Emacs
     mark, not Dired marks; use `C-<SPC>' (`set-mark-command') to set
     the mark at the first file's line (*note Setting Mark::).

`M-='
     Compare the current file with its latest backup file
     (`dired-backup-diff').  If the current file is itself a backup,
     compare it with the file it is a backup of; this way, you can
     compare a file with any one of its backups.

     The backup file is the first file given to `diff'.


File: emacs,  Node: Subdirectories in Dired,  Next: Subdir Switches,  Prev: Comparison in Dired,  Up: Dired

30.11 Subdirectories in Dired
=============================

A Dired buffer usually displays just one directory, but you can
optionally include its subdirectories as well.

   The simplest way to include multiple directories in one Dired buffer
is to specify the options `-lR' for running `ls'.  (If you give a
numeric argument when you run Dired, then you can specify these options
in the minibuffer.)  That produces a recursive directory listing showing
all subdirectories at all levels.

   More often, you will want to show only specific subdirectories.  You
can do this with `i' (`dired-maybe-insert-subdir'):

`i'
     Insert the contents of a subdirectory later in the buffer.

If you use this command on a line that describes a file which is a
directory, it inserts the contents of that directory into the same
Dired buffer, and moves there.  Inserted subdirectory contents follow
the top-level directory of the Dired buffer, just as they do in `ls
-lR' output.

   If the subdirectory's contents are already present in the buffer,
the `i' command just moves to it.

   In either case, `i' sets the Emacs mark before moving, so `C-u
C-<SPC>' returns to your previous position in the Dired buffer (*note
Setting Mark::).  You can also use `^' to return to the parent
directory in the same Dired buffer (*note Dired Visiting::).

   Use the `l' command (`dired-do-redisplay') to update the
subdirectory's contents, and use `C-u k' on the subdirectory header
line to remove the subdirectory listing (*note Dired Updating::).  You
can also hide and show inserted subdirectories (*note Hiding
Subdirectories::).


File: emacs,  Node: Subdir Switches,  Next: Subdirectory Motion,  Prev: Subdirectories in Dired,  Up: Dired

30.12 Subdirectory Switches in Dired
====================================

You can insert subdirectories with specified `ls' switches in Dired
buffers using `C-u i'.  You can change the `ls' switches of an already
inserted subdirectory at point using `C-u l'.

   Dired preserves the switches if you revert the buffer.  Deleting a
subdirectory forgets about its switches.

   Using `dired-undo' (*note Marks vs Flags::) to reinsert or delete
subdirectories that were inserted with explicit switches can bypass
Dired's machinery for remembering (or forgetting) switches.  Deleting a
subdirectory using `dired-undo' does not forget its switches.  When
later reinserted using `i', it will be reinserted using its old
switches.  Using `dired-undo' to reinsert a subdirectory that was
deleted using the regular Dired commands (not `dired-undo') will
originally insert it with its old switches.  Reverting the buffer,
however, will relist it using the buffer's default switches.  If any of
this yields problems, you can easily correct the situation using `C-u
i' or `C-u l'.

   Dired does not remember the `R' switch.  Inserting a subdirectory
with switches that include the `R' switch is equivalent to inserting
each of its subdirectories using all remaining switches.  For instance,
updating or killing a subdirectory that was inserted with the `R'
switch will not update or kill its subdirectories.

   The buffer's default switches do not affect subdirectories that were
inserted using explicitly specified switches.  In particular, commands
such as `s' that change the buffer's switches do not affect such
subdirectories.  (They do, however, affect subdirectories without
explicitly assigned switches.)

   You can make Dired forget about all subdirectory switches and relist
all subdirectories with the buffer's default switches using `M-x
dired-reset-subdir-switches'.  This also reverts the Dired buffer.


File: emacs,  Node: Subdirectory Motion,  Next: Hiding Subdirectories,  Prev: Subdir Switches,  Up: Dired

30.13 Moving Over Subdirectories
================================

When a Dired buffer lists subdirectories, you can use the page motion
commands `C-x [' and `C-x ]' to move by entire directories (*note
Pages::).

   The following commands move across, up and down in the tree of
directories within one Dired buffer.  They move to "directory header
lines", which are the lines that give a directory's name, at the
beginning of the directory's contents.

`C-M-n'
     Go to next subdirectory header line, regardless of level
     (`dired-next-subdir').

`C-M-p'
     Go to previous subdirectory header line, regardless of level
     (`dired-prev-subdir').

`C-M-u'
     Go up to the parent directory's header line (`dired-tree-up').

`C-M-d'
     Go down in the directory tree, to the first subdirectory's header
     line (`dired-tree-down').

`<'
     Move up to the previous directory-file line (`dired-prev-dirline').
     These lines are the ones that describe a directory as a file in its
     parent directory.

`>'
     Move down to the next directory-file line (`dired-prev-dirline').


File: emacs,  Node: Hiding Subdirectories,  Next: Dired Updating,  Prev: Subdirectory Motion,  Up: Dired

30.14 Hiding Subdirectories
===========================

"Hiding" a subdirectory means to make it invisible, except for its
header line.

`$'
     Hide or show the subdirectory that point is in, and move point to
     the next subdirectory (`dired-hide-subdir').  This is a toggle.  A
     numeric argument serves as a repeat count.

`M-$'
     Hide all subdirectories in this Dired buffer, leaving only their
     header lines (`dired-hide-all').  Or, if any subdirectory is
     currently hidden, make all subdirectories visible again.  You can
     use this command to get an overview in very deep directory trees
     or to move quickly to subdirectories far away.

   Ordinary Dired commands never consider files inside a hidden
subdirectory.  For example, the commands to operate on marked files
ignore files in hidden directories even if they are marked.  Thus you
can use hiding to temporarily exclude subdirectories from operations
without having to remove the Dired marks on files in those
subdirectories.

   *Note Dired Updating::, for how to insert or delete a subdirectory
listing.


File: emacs,  Node: Dired Updating,  Next: Dired and Find,  Prev: Hiding Subdirectories,  Up: Dired

30.15 Updating the Dired Buffer
===============================

This section describes commands to update the Dired buffer to reflect
outside (non-Dired) changes in the directories and files, and to delete
part of the Dired buffer.

`g'
     Update the entire contents of the Dired buffer (`revert-buffer').

`l'
     Update the specified files (`dired-do-redisplay').  You specify the
     files for `l' in the same way as for file operations.

`k'
     Delete the specified _file lines_--not the files, just the lines
     (`dired-do-kill-lines').

`s'
     Toggle between alphabetical order and date/time order
     (`dired-sort-toggle-or-edit').

`C-u s SWITCHES <RET>'
     Refresh the Dired buffer using SWITCHES as
     `dired-listing-switches'.

   Type `g' (`revert-buffer') to update the contents of the Dired
buffer, based on changes in the files and directories listed.  This
preserves all marks except for those on files that have vanished.
Hidden subdirectories are updated but remain hidden.

   To update only some of the files, type `l' (`dired-do-redisplay').
Like the Dired file-operating commands, this command operates on the
next N files (or previous -N files), or on the marked files if any, or
on the current file.  Updating the files means reading their current
status, then updating their lines in the buffer to indicate that status.

   If you use `l' on a subdirectory header line, it updates the
contents of the corresponding subdirectory.

   If you use `C-x d' or some other Dired command to visit a directory
that is already being shown in a Dired buffer, Dired switches to that
buffer but does not update it.  If the buffer is not up-to-date, Dired
displays a warning telling you to type <g> to update it.  You can also
tell Emacs to revert each Dired buffer automatically when you revisit
it, by setting the variable `dired-auto-revert-buffer' to a non-`nil'
value.

   To delete the specified _file lines_ from the buffer--not delete the
files--type `k' (`dired-do-kill-lines').  Like the file-operating
commands, this command operates on the next N files, or on the marked
files if any; but it does not operate on the current file as a last
resort.

   If you use `k' with a numeric prefix argument to kill the line for a
file that is a directory, which you have inserted in the Dired buffer
as a subdirectory, it removed that subdirectory line from the buffer as
well.  Typing `C-u k' on the header line for a subdirectory also
removes the subdirectory line from the Dired buffer.

   The `g' command brings back any individual lines that you have
killed in this way, but not subdirectories--you must use `i' to
reinsert a subdirectory.

   The files in a Dired buffers are normally listed in alphabetical
order by file names.  Alternatively Dired can sort them by date/time.
The Dired command `s' (`dired-sort-toggle-or-edit') switches between
these two sorting modes.  The mode line in a Dired buffer indicates
which way it is currently sorted--by name, or by date.

   `C-u s SWITCHES <RET>' lets you specify a new value for
`dired-listing-switches'.


File: emacs,  Node: Dired and Find,  Next: Wdired,  Prev: Dired Updating,  Up: Dired

30.16 Dired and `find'
======================

You can select a set of files for display in a Dired buffer more
flexibly by using the `find' utility to choose the files.

   To search for files with names matching a wildcard pattern use `M-x
find-name-dired'.  It reads arguments DIRECTORY and PATTERN, and
chooses all the files in DIRECTORY or its subdirectories whose
individual names match PATTERN.

   The files thus chosen are displayed in a Dired buffer, in which the
ordinary Dired commands are available.

   If you want to test the contents of files, rather than their names,
use `M-x find-grep-dired'.  This command reads two minibuffer
arguments, DIRECTORY and REGEXP; it chooses all the files in DIRECTORY
or its subdirectories that contain a match for REGEXP.  It works by
running the programs `find' and `grep'.  See also `M-x grep-find', in
*note Grep Searching::.  Remember to write the regular expression for
`grep', not for Emacs.  (An alternative method of showing files whose
contents match a given regexp is the `% g REGEXP' command, see *note
Marks vs Flags::.)

   The most general command in this series is `M-x find-dired', which
lets you specify any condition that `find' can test.  It takes two
minibuffer arguments, DIRECTORY and FIND-ARGS; it runs `find' in
DIRECTORY, passing FIND-ARGS to tell `find' what condition to test.  To
use this command, you need to know how to use `find'.

   The format of listing produced by these commands is controlled by
the variable `find-ls-option'.  This is a pair of options; the first
specifying how to call `find' to produce the file listing, and the
second telling Dired to parse the output.

   The command `M-x locate' provides a similar interface to the
`locate' program.  `M-x locate-with-filter' is similar, but keeps only
files whose names match a given regular expression.

   These buffers don't work entirely like ordinary Dired buffers: file
operations work, but do not always automatically update the buffer.
Reverting the buffer with `g' deletes all inserted subdirectories, and
erases all flags and marks.


File: emacs,  Node: Wdired,  Next: Image-Dired,  Prev: Dired and Find,  Up: Dired

30.17 Editing the Dired Buffer
==============================

Wdired is a special mode that allows you to perform file operations by
editing the Dired buffer directly (the "W" in "Wdired" stands for
"writable".)  To enter Wdired mode, type `C-x C-q'
(`dired-toggle-read-only') while in a Dired buffer.  Alternatively, use
the `Immediate / Edit File Names' menu item.

   While in Wdired mode, you can rename files by editing the file names
displayed in the Dired buffer.  All the ordinary Emacs editing
commands, including rectangle operations and `query-replace', are
available for this.  Once you are done editing, type `C-c C-c'
(`wdired-finish-edit').  This applies your changes and switches back to
ordinary Dired mode.

   Apart from simply renaming files, you can move a file to another
directory by typing in the new file name (either absolute or relative).
To mark a file for deletion, delete the entire file name.  To change
the target of a symbolic link, edit the link target name which appears
next to the link name.

   The rest of the text in the buffer, such as the file sizes and
modification dates, is marked read-only, so you can't edit it.
However, if you set `wdired-allow-to-change-permissions' to `t', you
can edit the file permissions.  For example, you can change
`-rw-r--r--' to `-rw-rw-rw-' to make a file world-writable.  These
changes also take effect when you type `C-c C-c'.


File: emacs,  Node: Image-Dired,  Next: Misc Dired Features,  Prev: Wdired,  Up: Dired

30.18 Viewing Image Thumbnails in Dired
=======================================

Image-Dired is a facility for browsing image files.  It provides viewing
the images either as thumbnails or in full size, either inside Emacs or
through an external viewer.

   To enter Image-Dired, mark the image files you want to look at in
the Dired buffer, using `m' as usual.  Then type `C-t d'
(`image-dired-display-thumbs').  This creates and switches to a buffer
containing image-dired, corresponding to the marked files.

   You can also enter Image-Dired directly by typing `M-x image-dired'.
This prompts for a directory; specify one that has image files.  This
creates thumbnails for all the images in that directory, and displays
them all in the "thumbnail buffer".  This takes a long time if the
directory contains many image files, and it asks for confirmation if
the number of image files exceeds
`image-dired-show-all-from-dir-max-files'.

   With point in the thumbnail buffer, you can type `RET'
(`image-dired-display-thumbnail-original-image') to display a sized
version of it in another window.  This sizes the image to fit the
window.  Use the arrow keys to move around in the buffer.  For easy
browsing, use `SPC' (`image-dired-display-next-thumbnail-original') to
advance and display the next image.  Typing `DEL'
(`image-dired-display-previous-thumbnail-original') backs up to the
previous thumbnail and displays that instead.

   To view and the image in its original size, either provide a prefix
argument (`C-u') before pressing `RET', or type `C-<RET>'
(`image-dired-thumbnail-display-external') to display the image in an
external viewer.  You must first configure
`image-dired-external-viewer'.

   You can delete images through Image-Dired also.  Type `d'
(`image-dired-flag-thumb-original-file') to flag the image file for
deletion in the Dired buffer.  You can also delete the thumbnail image
from the thumbnail buffer with `C-d' (`image-dired-delete-char').

   More advanced features include "image tags", which are metadata used
to categorize image files.  The tags are stored in a plain text file
configured by `image-dired-db-file'.

   To tag image files, mark them in the dired buffer (you can also mark
files in Dired from the thumbnail buffer by typing `m') and type `C-t
t' (`image-dired-tag-files').  This reads the tag name in the
minibuffer.  To mark files having a certain tag, type `C-t f'
(`image-dired-mark-tagged-files').  After marking image files with a
certain tag, you can use `C-t d' to view them.

   You can also tag a file directly from the thumbnail buffer by typing
`t t' and you can remove a tag by typing `t r'.  There is also a
special "tag" called "comment" for each file (it is not a tag in the
exact same sense as the other tags, it is handled slightly different).
That is used to enter a comment or description about the image.  You
comment a file from the thumbnail buffer by typing `c'.  You will be
prompted for a comment.  Type `C-t c' to add a comment from Dired
(`image-dired-dired-comment-files').

   Image-Dired also provides simple image manipulation.  In the
thumbnail buffer, type `L' to rotate the original image 90 degrees anti
clockwise, and `R' to rotate it 90 degrees clockwise.  This rotation is
lossless, and uses an external utility called JpegTRAN.


File: emacs,  Node: Misc Dired Features,  Prev: Image-Dired,  Up: Dired

30.19 Other Dired Features
==========================

The command `+' (`dired-create-directory') reads a directory name, and
creates that directory.  It signals an error if the directory already
exists.

   The command `M-s a C-s' (`dired-do-isearch') begins a "multi-file"
incremental search on the marked files.  If a search fails at the end
of a file, typing `C-s' advances to the next marked file and repeats
the search; at the end of the last marked file, the search wraps around
to the first marked file.  The command `M-s a M-C-s'
(`dired-do-isearch-regexp') does the same with a regular expression
search.  *Note Repeat Isearch::, for information about search
repetition.

   The command `w' (`dired-copy-filename-as-kill') puts the names of
the marked (or next N) files into the kill ring, as if you had killed
them with `C-w'.  The names are separated by a space.

   With a zero prefix argument, this uses the absolute file name of
each marked file.  With just `C-u' as the prefix argument, it uses file
names relative to the Dired buffer's default directory.  (This can
still contain slashes if in a subdirectory.)  As a special case, if
point is on a directory headerline, `w' gives you the absolute name of
that directory.  Any prefix argument or marked files are ignored in
this case.

   The main purpose of this command is so that you can yank the file
names into arguments for other Emacs commands.  It also displays what
it added to the kill ring, so you can use it to display the list of
currently marked files in the echo area.

   If the directory you are visiting is under version control (*note
Version Control::), then the normal VC diff and log commands will
operate on the selected files.

   The command `M-x dired-compare-directories' is used to compare the
current Dired buffer with another directory.  It marks all the files
that are "different" between the two directories.  It puts these marks
in all Dired buffers where these files are listed, which of course
includes the current buffer.

   The default comparison method (used if you type <RET> at the prompt)
is to compare just the file names--each file name that does not appear
in the other directory is "different".  You can specify more stringent
comparisons by entering a Lisp expression, which can refer to the
variables `size1' and `size2', the respective file sizes; `mtime1' and
`mtime2', the last modification times in seconds, as floating point
numbers; and `fa1' and `fa2', the respective file attribute lists (as
returned by the function `file-attributes').  This expression is
evaluated for each pair of like-named files, and if the expression's
value is non-`nil', those files are considered "different".

   For instance, the sequence `M-x dired-compare-directories <RET> (>
mtime1 mtime2) <RET>' marks files newer in this directory than in the
other, and marks files older in the other directory than in this one.
It also marks files with no counterpart, in both directories, as always.

   On the X Window System, Emacs supports the "drag and drop" protocol.
You can drag a file object from another program, and drop it onto a
Dired buffer; this either moves, copies, or creates a link to the file
in that directory.  Precisely which action is taken is determined by
the originating program.  Dragging files out of a Dired buffer is
currently not supported.


File: emacs,  Node: Calendar/Diary,  Next: Sending Mail,  Prev: Dired,  Up: Top

31 The Calendar and the Diary
*****************************

Emacs provides the functions of a desk calendar, with a diary of
planned or past events.  It also has facilities for managing your
appointments, and keeping track of how much time you spend working on
certain projects.

   To enter the calendar, type `M-x calendar'; this displays a
three-month calendar centered on the current month, with point on the
current date.  With a numeric argument, as in `C-u M-x calendar', it
prompts you for the month and year to be the center of the three-month
calendar.  The calendar uses its own buffer, whose major mode is
Calendar mode.

   `Mouse-3' in the calendar brings up a menu of operations on a
particular date; `Mouse-2' brings up a menu of commonly used calendar
features that are independent of any particular date.  To exit the
calendar, type `q'.

* Menu:

* Calendar Motion::     Moving through the calendar; selecting a date.
* Scroll Calendar::     Bringing earlier or later months onto the screen.
* Counting Days::       How many days are there between two dates?
* General Calendar::    Exiting or recomputing the calendar.
* Writing Calendar Files:: Writing calendars to files of various formats.
* Holidays::            Displaying dates of holidays.
* Sunrise/Sunset::      Displaying local times of sunrise and sunset.
* Lunar Phases::        Displaying phases of the moon.
* Other Calendars::     Converting dates to other calendar systems.
* Diary::               Displaying events from your diary.
* Appointments::        Reminders when it's time to do something.
* Importing Diary::     Converting diary events to/from other formats.
* Daylight Saving::     How to specify when daylight saving time is active.
* Time Intervals::      Keeping track of time intervals.

* Advanced Calendar/Diary Usage:: Advanced Calendar/Diary customization.


File: emacs,  Node: Calendar Motion,  Next: Scroll Calendar,  Up: Calendar/Diary

31.1 Movement in the Calendar
=============================

Calendar mode provides commands to move through the calendar in logical
units of time such as days, weeks, months, and years.  If you move
outside the three months originally displayed, the calendar display
"scrolls" automatically through time to make the selected date visible.
Moving to a date lets you view its holidays or diary entries, or
convert it to other calendars; moving by long time periods is also
useful simply to scroll the calendar.

* Menu:

* Calendar Unit Motion::      Moving by days, weeks, months, and years.
* Move to Beginning or End::  Moving to start/end of weeks, months, and years.
* Specified Dates::           Moving to the current date or another
                                specific date.


File: emacs,  Node: Calendar Unit Motion,  Next: Move to Beginning or End,  Up: Calendar Motion

31.1.1 Motion by Standard Lengths of Time
-----------------------------------------

The commands for movement in the calendar buffer parallel the commands
for movement in text.  You can move forward and backward by days,
weeks, months, and years.

`C-f'
     Move point one day forward (`calendar-forward-day').

`C-b'
     Move point one day backward (`calendar-backward-day').

`C-n'
     Move point one week forward (`calendar-forward-week').

`C-p'
     Move point one week backward (`calendar-backward-week').

`M-}'
     Move point one month forward (`calendar-forward-month').

`M-{'
     Move point one month backward (`calendar-backward-month').

`C-x ]'
     Move point one year forward (`calendar-forward-year').

`C-x ['
     Move point one year backward (`calendar-backward-year').

   The day and week commands are natural analogues of the usual Emacs
commands for moving by characters and by lines.  Just as `C-n' usually
moves to the same column in the following line, in Calendar mode it
moves to the same day in the following week.  And `C-p' moves to the
same day in the previous week.

   The arrow keys are equivalent to `C-f', `C-b', `C-n' and `C-p', just
as they normally are in other modes.

   The commands for motion by months and years work like those for
weeks, but move a larger distance.  The month commands `M-}' and `M-{'
move forward or backward by an entire month.  The year commands `C-x ]'
and `C-x [' move forward or backward a whole year.

   The easiest way to remember these commands is to consider months and
years analogous to paragraphs and pages of text, respectively.  But the
commands themselves are not quite analogous.  The ordinary Emacs
paragraph commands move to the beginning or end of a paragraph, whereas
these month and year commands move by an entire month or an entire
year, keeping the same date within the month or year.

   All these commands accept a numeric argument as a repeat count.  For
convenience, the digit keys and the minus sign specify numeric
arguments in Calendar mode even without the Meta modifier.  For example,
`100 C-f' moves point 100 days forward from its present location.


File: emacs,  Node: Move to Beginning or End,  Next: Specified Dates,  Prev: Calendar Unit Motion,  Up: Calendar Motion

31.1.2 Beginning or End of Week, Month or Year
----------------------------------------------

A week (or month, or year) is not just a quantity of days; we think of
weeks (months, years) as starting on particular dates.  So Calendar mode
provides commands to move to the start or end of a week, month or year:

`C-a'
     Move point to start of week (`calendar-beginning-of-week').  

`C-e'
     Move point to end of week (`calendar-end-of-week').  

`M-a'
     Move point to start of month (`calendar-beginning-of-month').  

`M-e'
     Move point to end of month (`calendar-end-of-month').  

`M-<'
     Move point to start of year (`calendar-beginning-of-year').  

`M->'
     Move point to end of year (`calendar-end-of-year').

   These commands also take numeric arguments as repeat counts, with the
repeat count indicating how many weeks, months, or years to move
backward or forward.

   By default, weeks begin on Sunday.  To make them begin on Monday
instead, set the variable `calendar-week-start-day' to 1.


File: emacs,  Node: Specified Dates,  Prev: Move to Beginning or End,  Up: Calendar Motion

31.1.3 Specified Dates
----------------------

Calendar mode provides commands for moving to a particular date
specified in various ways.

`g d'
     Move point to specified date (`calendar-goto-date').

`g D'
     Move point to specified day of year (`calendar-goto-day-of-year').

`g w'
     Move point to specified week of year (`calendar-iso-goto-week').

`o'
     Center calendar around specified month (`calendar-other-month').

`.'
     Move point to today's date (`calendar-goto-today').

   `g d' (`calendar-goto-date') prompts for a year, a month, and a day
of the month, and then moves to that date.  Because the calendar
includes all dates from the beginning of the current era, you must type
the year in its entirety; that is, type `1990', not `90'.

   `g D' (`calendar-goto-day-of-year') prompts for a year and day
number, and moves to that date.  Negative day numbers count backward
from the end of the year.  `g w' (`calendar-iso-goto-week') prompts for
a year and week number, and moves to that week.

   `o' (`calendar-other-month') prompts for a month and year, then
centers the three-month calendar around that month.

   You can return to today's date with `.' (`calendar-goto-today').


File: emacs,  Node: Scroll Calendar,  Next: Counting Days,  Prev: Calendar Motion,  Up: Calendar/Diary

31.2 Scrolling in the Calendar
==============================

The calendar display scrolls automatically through time when you move
out of the visible portion.  You can also scroll it manually.  Imagine
that the calendar window contains a long strip of paper with the months
on it.  Scrolling the calendar means moving the strip horizontally, so
that new months become visible in the window.

`>'
     Scroll calendar one month forward (`calendar-scroll-left').

`<'
     Scroll calendar one month backward (`calendar-scroll-right').

`C-v'
`<next>'
     Scroll forward by three months
     (`calendar-scroll-left-three-months').

`M-v'
`<prior>'
     Scroll backward by three months
     (`calendar-scroll-right-three-months').

   The most basic calendar scroll commands scroll by one month at a
time.  This means that there are two months of overlap between the
display before the command and the display after.  `>' scrolls the
calendar contents one month forward in time.  `<' scrolls the contents
one month backwards in time.

   The commands `C-v' and `M-v' scroll the calendar by an entire
"screenful"--three months--in analogy with the usual meaning of these
commands.  `C-v' makes later dates visible and `M-v' makes earlier
dates visible.  These commands take a numeric argument as a repeat
count; in particular, since `C-u' multiplies the next command by four,
typing `C-u C-v' scrolls the calendar forward by a year and typing `C-u
M-v' scrolls the calendar backward by a year.

   The function keys <next> and <prior> are equivalent to `C-v' and
`M-v', just as they are in other modes.


File: emacs,  Node: Counting Days,  Next: General Calendar,  Prev: Scroll Calendar,  Up: Calendar/Diary

31.3 Counting Days
==================

`M-='
     Display the number of days in the current region
     (`calendar-count-days-region').

   To determine the number of days in a range, set the mark on one date
using `C-SPC', move point to another date, and type `M-='
(`calendar-count-days-region').  The numbers of days shown is
_inclusive_; that is, it includes the days specified by mark and point.


File: emacs,  Node: General Calendar,  Next: Writing Calendar Files,  Prev: Counting Days,  Up: Calendar/Diary

31.4 Miscellaneous Calendar Commands
====================================

`p d'
     Display day-in-year (`calendar-print-day-of-year').

`C-c C-l'
     Regenerate the calendar window (`calendar-redraw').

`SPC'
     Scroll the next window up (`scroll-other-window').

`DEL'
     Scroll the next window down (`scroll-other-window-down').

`q'
     Exit from calendar (`calendar-exit').

   To display the number of days elapsed since the start of the year, or
the number of days remaining in the year, type the `p d' command
(`calendar-print-day-of-year').  This displays both of those numbers in
the echo area.  The count of days elapsed includes the selected date.
The count of days remaining does not include that date.

   If the calendar window text gets corrupted, type `C-c C-l'
(`calendar-redraw') to redraw it.  (This can only happen if you use
non-Calendar-mode editing commands.)

   In Calendar mode, you can use `SPC' (`scroll-other-window') and
`DEL' (`scroll-other-window-down') to scroll the other window (if there
is one) up or down, respectively.  This is handy when you display a
list of holidays or diary entries in another window.

   To exit from the calendar, type `q' (`calendar-exit').  This buries
all buffers related to the calendar, selecting other buffers.  (If a
frame contains a dedicated calendar window, exiting from the calendar
deletes or iconifies that frame depending on the value of
`calendar-remove-frame-by-deleting'.)


File: emacs,  Node: Writing Calendar Files,  Next: Holidays,  Prev: General Calendar,  Up: Calendar/Diary

31.5 Writing Calendar Files
===========================

You can write calendars and diary entries to HTML and LaTeX files.

   The Calendar HTML commands produce files of HTML code that contain
calendar and diary entries.  Each file applies to one month, and has a
name of the format `YYYY-MM.html', where YYYY and MM are the four-digit
year and two-digit month, respectively.  The variable
`cal-html-directory' specifies the default output directory for the
HTML files.

   Diary entries enclosed by `<' and `>' are interpreted as HTML tags
(for example: this is a diary entry with <font color="red">some red
text</font>).  You can change the overall appearance of the displayed
HTML pages (for example, the color of various page elements, header
styles) via a stylesheet `cal.css' in the directory containing the HTML
files (see the value of the variable `cal-html-css-default' for
relevant style settings).

`H m'
     Generate a one-month calendar (`cal-html-cursor-month').

`H y'
     Generate a calendar file for each month of a year, as well as an
     index page (`cal-html-cursor-year').  By default, this command
     writes files to a YYYY subdirectory - if this is altered some
     hyperlinks between years will not work.

   If the variable `cal-html-print-day-number-flag' is non-`nil', then
the monthly calendars show the day-of-the-year number. The variable
`cal-html-year-index-cols' specifies the number of columns in the
yearly index page.

   The Calendar LaTeX commands produce a buffer of LaTeX code that
prints as a calendar.  Depending on the command you use, the printed
calendar covers the day, week, month or year that point is in.

`t m'
     Generate a one-month calendar (`cal-tex-cursor-month').

`t M'
     Generate a sideways-printing one-month calendar
     (`cal-tex-cursor-month-landscape').

`t d'
     Generate a one-day calendar (`cal-tex-cursor-day').

`t w 1'
     Generate a one-page calendar for one week (`cal-tex-cursor-week').

`t w 2'
     Generate a two-page calendar for one week (`cal-tex-cursor-week2').

`t w 3'
     Generate an ISO-style calendar for one week
     (`cal-tex-cursor-week-iso').

`t w 4'
     Generate a calendar for one Monday-starting week
     (`cal-tex-cursor-week-monday').

`t f w'
     Generate a Filofax-style two-weeks-at-a-glance calendar
     (`cal-tex-cursor-filofax-2week').

`t f W'
     Generate a Filofax-style one-week-at-a-glance calendar
     (`cal-tex-cursor-filofax-week').

`t y'
     Generate a calendar for one year (`cal-tex-cursor-year').

`t Y'
     Generate a sideways-printing calendar for one year
     (`cal-tex-cursor-year-landscape').

`t f y'
     Generate a Filofax-style calendar for one year
     (`cal-tex-cursor-filofax-year').

   Some of these commands print the calendar sideways (in "landscape
mode"), so it can be wider than it is long.  Some of them use Filofax
paper size (3.75in x 6.75in).  All of these commands accept a prefix
argument, which specifies how many days, weeks, months or years to print
(starting always with the selected one).

   If the variable `cal-tex-holidays' is non-`nil' (the default), then
the printed calendars show the holidays in `calendar-holidays'.  If the
variable `cal-tex-diary' is non-`nil' (the default is `nil'), diary
entries are included also (in monthly, filofax, and iso-week calendars
only).  If the variable `cal-tex-rules' is non-`nil' (the default is
`nil'), the calendar displays ruled pages in styles that have
sufficient room.  Consult the documentation of the individual cal-tex
functions to see which calendars support which features.

   You can use the variable `cal-tex-preamble-extra' to insert extra
LaTeX commands in the preamble of the generated document if you need to.


File: emacs,  Node: Holidays,  Next: Sunrise/Sunset,  Prev: Writing Calendar Files,  Up: Calendar/Diary

31.6 Holidays
=============

The Emacs calendar knows about many major and minor holidays, and can
display them.  You can add your own holidays to the default list.

`Mouse-3 Holidays'
`h'
     Display holidays for the selected date
     (`calendar-cursor-holidays').

`x'
     Mark holidays in the calendar window (`calendar-mark-holidays').

`u'
     Unmark calendar window (`calendar-unmark').

`a'
     List all holidays for the displayed three months in another window
     (`calendar-list-holidays').

`M-x holidays'
     List all holidays for three months around today's date in another
     window.

`M-x list-holidays'
     List holidays in another window for a specified range of years.

   To see if any holidays fall on a given date, position point on that
date in the calendar window and use the `h' command.  Alternatively,
click on that date with `Mouse-3' and then choose `Holidays' from the
menu that appears.  Either way, this displays the holidays for that
date, in the echo area if they fit there, otherwise in a separate
window.

   To view the distribution of holidays for all the dates shown in the
calendar, use the `x' command.  This displays the dates that are
holidays in a different face.  *Note calendar-holiday-marker: Calendar
Customizing.    The command applies both to the currently visible
months and to other months that subsequently become visible by
scrolling.  To turn marking off and erase the current marks, type `u',
which also erases any diary marks (*note Diary::).  If the variable
`calendar-mark-holidays-flag' is non-`nil', creating or updating the
calendar marks holidays automatically.

   To get even more detailed information, use the `a' command, which
displays a separate buffer containing a list of all holidays in the
current three-month range.  You can use <SPC> and <DEL> in the calendar
window to scroll that list up and down, respectively.

   The command `M-x holidays' displays the list of holidays for the
current month and the preceding and succeeding months; this works even
if you don't have a calendar window.  If the variable
`calendar-view-holidays-initially-flag' is non-`nil', creating the
calendar displays holidays in this way.  If you want the list of
holidays centered around a different month, use `C-u M-x holidays',
which prompts for the month and year.

   The holidays known to Emacs include United States holidays and the
major Bah�'�, Chinese, Christian, Islamic, and Jewish holidays; also the
solstices and equinoxes.

   The command `M-x holiday-list' displays the list of holidays for a
range of years.  This function asks you for the starting and stopping
years, and allows you to choose all the holidays or one of several
categories of holidays.  You can use this command even if you don't have
a calendar window.

   The dates used by Emacs for holidays are based on _current
practice_, not historical fact.  For example Veteran's Day began in
1919, but is shown in earlier years.


File: emacs,  Node: Sunrise/Sunset,  Next: Lunar Phases,  Prev: Holidays,  Up: Calendar/Diary

31.7 Times of Sunrise and Sunset
================================

Special calendar commands can tell you, to within a minute or two, the
times of sunrise and sunset for any date.

`Mouse-3 Sunrise/sunset'
`S'
     Display times of sunrise and sunset for the selected date
     (`calendar-sunrise-sunset').

`M-x sunrise-sunset'
     Display times of sunrise and sunset for today's date.

`C-u M-x sunrise-sunset'
     Display times of sunrise and sunset for a specified date.

`M-x calendar-sunrise-sunset-month'
     Display times of sunrise and sunset for the selected month.

   Within the calendar, to display the _local times_ of sunrise and
sunset in the echo area, move point to the date you want, and type `S'.
Alternatively, click `Mouse-3' on the date, then choose
`Sunrise/sunset' from the menu that appears.  The command `M-x
sunrise-sunset' is available outside the calendar to display this
information for today's date or a specified date.  To specify a date
other than today, use `C-u M-x sunrise-sunset', which prompts for the
year, month, and day.

   You can display the times of sunrise and sunset for any location and
any date with `C-u C-u M-x sunrise-sunset'.  This asks you for a
longitude, latitude, number of minutes difference from Coordinated
Universal Time, and date, and then tells you the times of sunrise and
sunset for that location on that date.

   Because the times of sunrise and sunset depend on the location on
earth, you need to tell Emacs your latitude, longitude, and location
name before using these commands.  Here is an example of what to set:

     (setq calendar-latitude 40.1)
     (setq calendar-longitude -88.2)
     (setq calendar-location-name "Urbana, IL")

Use one decimal place in the values of `calendar-latitude' and
`calendar-longitude'.

   Your time zone also affects the local time of sunrise and sunset.
Emacs usually gets time zone information from the operating system, but
if these values are not what you want (or if the operating system does
not supply them), you must set them yourself.  Here is an example:

     (setq calendar-time-zone -360)
     (setq calendar-standard-time-zone-name "CST")
     (setq calendar-daylight-time-zone-name "CDT")

The value of `calendar-time-zone' is the number of minutes difference
between your local standard time and Coordinated Universal Time
(Greenwich time).  The values of `calendar-standard-time-zone-name' and
`calendar-daylight-time-zone-name' are the abbreviations used in your
time zone.  Emacs displays the times of sunrise and sunset _corrected
for daylight saving time_.  *Note Daylight Saving::, for how daylight
saving time is determined.

   As a user, you might find it convenient to set the calendar location
variables for your usual physical location in your `.emacs' file.  If
you are a system administrator, you may want to set these variables for
all users in a `default.el' file.  *Note Init File::.


File: emacs,  Node: Lunar Phases,  Next: Other Calendars,  Prev: Sunrise/Sunset,  Up: Calendar/Diary

31.8 Phases of the Moon
=======================

These calendar commands display the dates and times of the phases of
the moon (new moon, first quarter, full moon, last quarter).  This
feature is useful for debugging problems that "depend on the phase of
the moon".

`M'
     Display the dates and times for all the quarters of the moon for
     the three-month period shown (`calendar-lunar-phases').

`M-x lunar-phases'
     Display dates and times of the quarters of the moon for three
     months around today's date.

   Within the calendar, use the `M' command to display a separate
buffer of the phases of the moon for the current three-month range.  The
dates and times listed are accurate to within a few minutes.

   Outside the calendar, use the command `M-x lunar-phases' to display
the list of the phases of the moon for the current month and the
preceding and succeeding months.  For information about a different
month, use `C-u M-x lunar-phases', which prompts for the month and year.

   The dates and times given for the phases of the moon are given in
local time (corrected for daylight saving, when appropriate).  See the
discussion in the previous section.  *Note Sunrise/Sunset::.


File: emacs,  Node: Other Calendars,  Next: Diary,  Prev: Lunar Phases,  Up: Calendar/Diary

31.9 Conversion To and From Other Calendars
===========================================

The Emacs calendar displayed is _always_ the Gregorian calendar,
sometimes called the "new style" calendar, which is used in most of the
world today.  However, this calendar did not exist before the sixteenth
century and was not widely used before the eighteenth century; it did
not fully displace the Julian calendar and gain universal acceptance
until the early twentieth century.  The Emacs calendar can display any
month since January, year 1 of the current era, but the calendar
displayed is always the Gregorian, even for a date at which the
Gregorian calendar did not exist.

   While Emacs cannot display other calendars, it can convert dates to
and from several other calendars.

* Menu:

* Calendar Systems::       The calendars Emacs understands
                             (aside from Gregorian).
* To Other Calendar::      Converting the selected date to various calendars.
* From Other Calendar::    Moving to a date specified in another calendar.
* Mayan Calendar::         Moving to a date specified in a Mayan calendar.


File: emacs,  Node: Calendar Systems,  Next: To Other Calendar,  Up: Other Calendars

31.9.1 Supported Calendar Systems
---------------------------------

The ISO commercial calendar is often used in business.

   The Julian calendar, named after Julius Caesar, was the one used in
Europe throughout medieval times, and in many countries up until the
nineteenth century.

   Astronomers use a simple counting of days elapsed since noon, Monday,
January 1, 4713 B.C. on the Julian calendar.  The number of days elapsed
is called the "Julian day number" or the "Astronomical day number".

   The Hebrew calendar is used by tradition in the Jewish religion.  The
Emacs calendar program uses the Hebrew calendar to determine the dates
of Jewish holidays.  Hebrew calendar dates begin and end at sunset.

   The Islamic calendar is used in many predominantly Islamic countries.
Emacs uses it to determine the dates of Islamic holidays.  There is no
universal agreement in the Islamic world about the calendar; Emacs uses
a widely accepted version, but the precise dates of Islamic holidays
often depend on proclamation by religious authorities, not on
calculations.  As a consequence, the actual dates of observance can vary
slightly from the dates computed by Emacs.  Islamic calendar dates begin
and end at sunset.

   The French Revolutionary calendar was created by the Jacobins after
the 1789 revolution, to represent a more secular and nature-based view
of the annual cycle, and to install a 10-day week in a rationalization
measure similar to the metric system.  The French government officially
abandoned this calendar at the end of 1805.

   The Maya of Central America used three separate, overlapping calendar
systems, the _long count_, the _tzolkin_, and the _haab_.  Emacs knows
about all three of these calendars.  Experts dispute the exact
correlation between the Mayan calendar and our calendar; Emacs uses the
Goodman-Martinez-Thompson correlation in its calculations.

   The Copts use a calendar based on the ancient Egyptian solar
calendar.  Their calendar consists of twelve 30-day months followed by
an extra five-day period.  Once every fourth year they add a leap day
to this extra period to make it six days.  The Ethiopic calendar is
identical in structure, but has different year numbers and month names.

   The Persians use a solar calendar based on a design of Omar Khayyam.
Their calendar consists of twelve months of which the first six have 31
days, the next five have 30 days, and the last has 29 in ordinary years
and 30 in leap years.  Leap years occur in a complicated pattern every
four or five years.  The calendar implemented here is the arithmetical
Persian calendar championed by Birashk, based on a 2,820-year cycle.
It differs from the astronomical Persian calendar, which is based on
astronomical events.  As of this writing the first future discrepancy
is projected to occur on March 20, 2025.  It is currently not clear
what the official calendar of Iran will be at that time.

   The Chinese calendar is a complicated system of lunar months arranged
into solar years.  The years go in cycles of sixty, each year containing
either twelve months in an ordinary year or thirteen months in a leap
year; each month has either 29 or 30 days.  Years, ordinary months, and
days are named by combining one of ten "celestial stems" with one of
twelve "terrestrial branches" for a total of sixty names that are
repeated in a cycle of sixty.

   The Bah�'� calendar system is based on a solar cycle of 19 months
with 19 days each.  The four remaining "intercalary" days are placed
between the 18th and 19th months.


File: emacs,  Node: To Other Calendar,  Next: From Other Calendar,  Prev: Calendar Systems,  Up: Other Calendars

31.9.2 Converting To Other Calendars
------------------------------------

The following commands describe the selected date (the date at point)
in various other calendar systems:

`Mouse-3  Other calendars'
`p o'
     Display the selected date in various other calendars.
     (`calendar-print-other-dates').  

`p c'
     Display ISO commercial calendar equivalent for selected day
     (`calendar-iso-print-date').  

`p j'
     Display Julian date for selected day
     (`calendar-julian-print-date').  

`p a'
     Display astronomical (Julian) day number for selected day
     (`calendar-astro-print-day-number').  

`p h'
     Display Hebrew date for selected day
     (`calendar-hebrew-print-date').  

`p i'
     Display Islamic date for selected day
     (`calendar-islamic-print-date').  

`p f'
     Display French Revolutionary date for selected day
     (`calendar-french-print-date').  

`p b'
     Display Bah�'� date for selected day (`calendar-bahai-print-date').  

`p C'
     Display Chinese date for selected day
     (`calendar-chinese-print-date').  

`p k'
     Display Coptic date for selected day
     (`calendar-coptic-print-date').  

`p e'
     Display Ethiopic date for selected day
     (`calendar-ethiopic-print-date').  

`p p'
     Display Persian date for selected day
     (`calendar-persian-print-date').  

`p m'
     Display Mayan date for selected day (`calendar-mayan-print-date').

   Otherwise, move point to the date you want to convert, then type the
appropriate command starting with `p' from the table above.  The prefix
`p' is a mnemonic for "print", since Emacs "prints" the equivalent date
in the echo area. `p o' displays the date in all forms known to Emacs.
You can also use `Mouse-3' and then choose `Other calendars' from the
menu that appears.  This displays the equivalent forms of the date in
all the calendars Emacs understands, in the form of a menu.  (Choosing
an alternative from this menu doesn't actually do anything--the menu is
used only for display.)


File: emacs,  Node: From Other Calendar,  Next: Mayan Calendar,  Prev: To Other Calendar,  Up: Other Calendars

31.9.3 Converting From Other Calendars
--------------------------------------

You can use the other supported calendars to specify a date to move to.
This section describes the commands for doing this using calendars
other than Mayan; for the Mayan calendar, see the following section.

`g c'
     Move to a date specified in the ISO commercial calendar
     (`calendar-iso-goto-date').

`g w'
     Move to a week specified in the ISO commercial calendar
     (`calendar-iso-goto-week').

`g j'
     Move to a date specified in the Julian calendar
     (`calendar-julian-goto-date').

`g a'
     Move to a date specified with an astronomical (Julian) day number
     (`calendar-astro-goto-day-number').

`g b'
     Move to a date specified in the Bah�'� calendar
     (`calendar-bahai-goto-date').

`g h'
     Move to a date specified in the Hebrew calendar
     (`calendar-hebrew-goto-date').

`g i'
     Move to a date specified in the Islamic calendar
     (`calendar-islamic-goto-date').

`g f'
     Move to a date specified in the French Revolutionary calendar
     (`calendar-french-goto-date').

`g C'
     Move to a date specified in the Chinese calendar
     (`calendar-chinese-goto-date').

`g p'
     Move to a date specified in the Persian calendar
     (`calendar-persian-goto-date').

`g k'
     Move to a date specified in the Coptic calendar
     (`calendar-coptic-goto-date').

`g e'
     Move to a date specified in the Ethiopic calendar
     (`calendar-ethiopic-goto-date').

   These commands ask you for a date on the other calendar, move point
to the Gregorian calendar date equivalent to that date, and display the
other calendar's date in the echo area.  Emacs uses strict completion
(*note Completion Exit::) whenever it asks you to type a month name, so
you don't have to worry about the spelling of Hebrew, Islamic, or
French names.

   One common issue concerning the Hebrew calendar is the computation
of the anniversary of a date of death, called a "yahrzeit".  The Emacs
calendar includes a facility for such calculations.  If you are in the
calendar, the command `M-x calendar-hebrew-list-yahrzeits' asks you for
a range of years and then displays a list of the yahrzeit dates for
those years for the date given by point.  If you are not in the
calendar, this command first asks you for the date of death and the
range of years, and then displays the list of yahrzeit dates.


File: emacs,  Node: Mayan Calendar,  Prev: From Other Calendar,  Up: Other Calendars

31.9.4 Converting from the Mayan Calendar
-----------------------------------------

Here are the commands to select dates based on the Mayan calendar:

`g m l'
     Move to a date specified by the long count calendar
     (`calendar-mayan-goto-long-count-date').

`g m n t'
     Move to the next occurrence of a place in the tzolkin calendar
     (`calendar-mayan-next-tzolkin-date').

`g m p t'
     Move to the previous occurrence of a place in the tzolkin calendar
     (`calendar-mayan-previous-tzolkin-date').

`g m n h'
     Move to the next occurrence of a place in the haab calendar
     (`calendar-mayan-next-haab-date').

`g m p h'
     Move to the previous occurrence of a place in the haab calendar
     (`calendar-mayan-previous-haab-date').

`g m n c'
     Move to the next occurrence of a place in the calendar round
     (`calendar-mayan-next-calendar-round-date').

`g m p c'
     Move to the previous occurrence of a place in the calendar round
     (`calendar-mayan-previous-calendar-round-date').

   To understand these commands, you need to understand the Mayan
calendars.  The "long count" is a counting of days with these units:

     1 kin = 1 day   1 uinal = 20 kin   1 tun = 18 uinal
     1 katun = 20 tun   1 baktun = 20 katun

Thus, the long count date 12.16.11.16.6 means 12 baktun, 16 katun, 11
tun, 16 uinal, and 6 kin.  The Emacs calendar can handle Mayan long
count dates as early as 7.17.18.13.3, but no earlier.  When you use the
`g m l' command, type the Mayan long count date with the baktun, katun,
tun, uinal, and kin separated by periods.

   The Mayan tzolkin calendar is a cycle of 260 days formed by a pair of
independent cycles of 13 and 20 days.  Since this cycle repeats
endlessly, Emacs provides commands to move backward and forward to the
previous or next point in the cycle.  Type `g m p t' to go to the
previous tzolkin date; Emacs asks you for a tzolkin date and moves point
to the previous occurrence of that date.  Similarly, type `g m n t' to
go to the next occurrence of a tzolkin date.

   The Mayan haab calendar is a cycle of 365 days arranged as 18 months
of 20 days each, followed by a 5-day monthless period.  Like the tzolkin
cycle, this cycle repeats endlessly, and there are commands to move
backward and forward to the previous or next point in the cycle.  Type
`g m p h' to go to the previous haab date; Emacs asks you for a haab
date and moves point to the previous occurrence of that date.
Similarly, type `g m n h' to go to the next occurrence of a haab date.

   The Maya also used the combination of the tzolkin date and the haab
date.  This combination is a cycle of about 52 years called a _calendar
round_.  If you type `g m p c', Emacs asks you for both a haab and a
tzolkin date and then moves point to the previous occurrence of that
combination.  Use `g m n c' to move point to the next occurrence of a
combination.  These commands signal an error if the haab/tzolkin date
combination you have typed is impossible.

   Emacs uses strict completion (*note Completion Exit::) whenever it
asks you to type a Mayan name, so you don't have to worry about
spelling.


File: emacs,  Node: Diary,  Next: Appointments,  Prev: Other Calendars,  Up: Calendar/Diary

31.10 The Diary
===============

The Emacs diary keeps track of appointments or other events on a daily
basis, in conjunction with the calendar.  To use the diary feature, you
must first create a "diary file" containing a list of events and their
dates.  Then Emacs can automatically pick out and display the events
for today, for the immediate future, or for any specified date.

   The name of the diary file is specified by the variable
`diary-file'; `~/diary' is the default.  Here's an example showing what
that file looks like:

     12/22/2012  Twentieth wedding anniversary!!
     &1/1.       Happy New Year!
     10/22       Ruth's birthday.
     * 21, *:    Payday
     Tuesday--weekly meeting with grad students at 10am
              Supowit, Shen, Bitner, and Kapoor to attend.
     1/13/89     Friday the thirteenth!!
     &thu 4pm    squash game with Lloyd.
     mar 16      Dad's birthday
     April 15, 2013 Income tax due.
     &* 15       time cards due.

This format is essentially the same as the one used by the separate
`calendar' utility that is present on some Unix systems.  This example
uses extra spaces to align the event descriptions of most of the
entries.  Such formatting is purely a matter of taste.

   Although you probably will start by creating a diary manually, Emacs
provides a number of commands to let you view, add, and change diary
entries.

* Menu:

* Displaying the Diary::   Viewing diary entries and associated calendar dates.
* Format of Diary File::   Entering events in your diary.
* Date Formats::           Various ways you can specify dates.
* Adding to Diary::        Commands to create diary entries.
* Special Diary Entries::  Anniversaries, blocks of dates, cyclic entries, etc.


File: emacs,  Node: Displaying the Diary,  Next: Format of Diary File,  Up: Diary

31.10.1 Displaying the Diary
----------------------------

Once you have created a diary file, you can use the calendar to view
it.  You can also view today's events outside of Calendar mode.  In the
following, key bindings refer to the Calendar buffer.

`Mouse-3 Diary'
`d'
     Display all diary entries for the selected date
     (`diary-view-entries').

`s'
     Display the entire diary file (`diary-show-all-entries').

`m'
     Mark all visible dates that have diary entries
     (`diary-mark-entries').

`u'
     Unmark the calendar window (`calendar-unmark').

`M-x diary-print-entries'
     Print hard copy of the diary display as it appears.

`M-x diary'
     Display all diary entries for today's date.

`M-x diary-mail-entries'
     Mail yourself email reminders about upcoming diary entries.

   Displaying the diary entries with `d' shows in a separate window the
diary entries for the selected date in the calendar.  The mode line of
the new window shows the date of the diary entries.  Holidays are shown
either in the buffer or in the mode line, depending on the display
method you choose (*note Diary Display::).  If you specify a numeric
argument with `d', it shows all the diary entries for that many
successive days.  Thus, `2 d' displays all the entries for the selected
date and for the following day.

   Another way to display the diary entries for a date is to click
`Mouse-3' on the date, and then choose `Diary entries' from the menu
that appears.  If the variable `calendar-view-diary-initially-flag' is
non-`nil', creating the calendar lists the diary entries for the
current date (provided the current date is visible).

   To get a broader view of which days are mentioned in the diary, use
the `m' command.  This marks the dates that have diary entries in a
different face.  *Note diary-entry-marker: Calendar Customizing.

   This command applies both to the months that are currently visible
and to those that subsequently become visible after scrolling.  To turn
marking off and erase the current marks, type `u', which also turns off
holiday marks (*note Holidays::).  If the variable
`calendar-mark-diary-entries-flag' is non-`nil', creating or updating
the calendar marks diary dates automatically.

   To see the full diary file, rather than just some of the entries, use
the `s' command.

   The command `M-x diary' displays the diary entries for the current
date, independently of the calendar display, and optionally for the next
few days as well; the variable `diary-number-of-entries' specifies how
many days to include.  *Note diary-number-of-entries: Diary Customizing.

   If you put `(diary)' in your `.emacs' file, this automatically
displays a window with the day's diary entries when you start Emacs.

   Some people like to receive email notifications of events in their
diary.  To send such mail to yourself, use the command `M-x
diary-mail-entries'.  A prefix argument specifies how many days
(starting with today) to check; otherwise, the variable
`diary-mail-days' says how many days.


File: emacs,  Node: Format of Diary File,  Next: Date Formats,  Prev: Displaying the Diary,  Up: Diary

31.10.2 The Diary File
----------------------

Your "diary file" is a file that records events associated with
particular dates.  The name of the diary file is specified by the
variable `diary-file'; `~/diary' is the default.  The `calendar'
utility program supports a subset of the format allowed by the Emacs
diary facilities, so you can use that utility to view the diary file,
with reasonable results aside from the entries it cannot understand.

   Each entry in the diary file describes one event and consists of one
or more lines.  An entry always begins with a date specification at the
left margin.  The rest of the entry is simply text to describe the
event.  If the entry has more than one line, then the lines after the
first must begin with whitespace to indicate they continue a previous
entry.  Lines that do not begin with valid dates and do not continue a
preceding entry are ignored.

   You can also use a format where the first line of a diary entry
consists only of the date or day name (with no following blanks or
punctuation).  For example:

     02/11/2012
           Bill B. visits Princeton today
           2pm Cognitive Studies Committee meeting
           2:30-5:30 Liz at Lawrenceville
           4:00pm Dentist appt
           7:30pm Dinner at George's
           8:00-10:00pm concert

This entry will have a different appearance if you use the simple diary
display (*note Diary Display::).  The simple diary display omits the
date line at the beginning; only the continuation lines appear.  This
style of entry looks neater when you display just a single day's
entries, but can cause confusion if you ask for more than one day's
entries.

   You can inhibit the marking of certain diary entries in the calendar
window; to do this, insert the string that `diary-nonmarking-symbol'
specifies (default `&') at the beginning of the entry, before the date.
This has no effect on display of the entry in the diary window; it only
affects marks on dates in the calendar window.  Nonmarking entries are
especially useful for generic entries that would otherwise mark many
different dates.


File: emacs,  Node: Date Formats,  Next: Adding to Diary,  Prev: Format of Diary File,  Up: Diary

31.10.3 Date Formats
--------------------

Here are some sample diary entries, illustrating different ways of
formatting a date.  The examples all show dates in American order
(month, day, year), but Calendar mode supports European order (day,
month, year) and ISO order (year, month, day) as options.

     4/20/12  Switch-over to new tabulation system
     apr. 25  Start tabulating annual results
     4/30  Results for April are due
     */25  Monthly cycle finishes
     Friday  Don't leave without backing up files

   The first entry appears only once, on April 20, 2012.  The second and
third appear every year on the specified dates, and the fourth uses a
wildcard (asterisk) for the month, so it appears on the 25th of every
month.  The final entry appears every week on Friday.

   You can use just numbers to express a date, as in `MONTH/DAY' or
`MONTH/DAY/YEAR'.  This must be followed by a nondigit.  In the date
itself, MONTH and DAY are numbers of one or two digits.  The optional
YEAR is also a number, and may be abbreviated to the last two digits;
that is, you can use `11/12/2012' or `11/12/12'.

   Dates can also have the form `MONTHNAME DAY' or `MONTHNAME DAY,
YEAR', where the month's name can be spelled in full or abbreviated
(with or without a period).  The preferred abbreviations for month and
day names can be set using the variables `calendar-abbrev-length',
`calendar-month-abbrev-array', and `calendar-day-abbrev-array'.  The
default is to use the first three letters of a name as its
abbreviation.  Case is not significant.

   A date may be "generic"; that is, partially unspecified.  Then the
entry applies to all dates that match the specification.  If the date
does not contain a year, it is generic and applies to any year.
Alternatively, MONTH, DAY, or YEAR can be `*'; this matches any month,
day, or year, respectively.  Thus, a diary entry `3/*/*' matches any
day in March of any year; so does `march *'.

   If you prefer the European style of writing dates (in which the day
comes before the month), or the ISO style (in which the order is year,
month, day), type `M-x calendar-set-date-style' while in the calendar,
or customize the variable `calendar-date-style'.  This affects how
diary dates are interpreted, date display, and the order in which some
commands expect their arguments to be given.

   You can use the name of a day of the week as a generic date which
applies to any date falling on that day of the week.  You can abbreviate
the day of the week as described above, or spell it in full; case is not
significant.


File: emacs,  Node: Adding to Diary,  Next: Special Diary Entries,  Prev: Date Formats,  Up: Diary

31.10.4 Commands to Add to the Diary
------------------------------------

While in the calendar, there are several commands to create diary
entries.  The basic commands are listed here; more sophisticated
commands are in the next section (*note Special Diary Entries::).
Entries can also be based on non-Gregorian calendars.  *Note
Non-Gregorian Diary::.

`i d'
     Add a diary entry for the selected date (`diary-insert-entry').

`i w'
     Add a diary entry for the selected day of the week
     (`diary-insert-weekly-entry').

`i m'
     Add a diary entry for the selected day of the month
     (`diary-insert-monthly-entry').

`i y'
     Add a diary entry for the selected day of the year
     (`diary-insert-yearly-entry').

   You can make a diary entry for a specific date by selecting that date
in the calendar window and typing the `i d' command.  This command
displays the end of your diary file in another window and inserts the
date; you can then type the rest of the diary entry.

   If you want to make a diary entry that applies to a specific day of
the week, select that day of the week (any occurrence will do) and type
`i w'.  This inserts the day-of-week as a generic date; you can then
type the rest of the diary entry.  You can make a monthly diary entry in
the same fashion: select the day of the month, use the `i m' command,
and type the rest of the entry.  Similarly, you can insert a yearly
diary entry with the `i y' command.

   All of the above commands make marking diary entries by default.  To
make a nonmarking diary entry, give a prefix argument to the command.
For example, `C-u i w' makes a nonmarking weekly diary entry.

   When you modify the diary file, be sure to save the file before
exiting Emacs.  Saving the diary file after using any of the above
insertion commands will automatically update the diary marks in the
calendar window, if appropriate.  You can use the command
`calendar-redraw' to force an update at any time.


File: emacs,  Node: Special Diary Entries,  Prev: Adding to Diary,  Up: Diary

31.10.5 Special Diary Entries
-----------------------------

In addition to entries based on calendar dates, the diary file can
contain "sexp entries" for regular events such as anniversaries.  These
entries are based on Lisp expressions (sexps) that Emacs evaluates as
it scans the diary file.  Instead of a date, a sexp entry contains `%%'
followed by a Lisp expression which must begin and end with
parentheses.  The Lisp expression determines which dates the entry
applies to.

   Calendar mode provides commands to insert certain commonly used sexp
entries:

`i a'
     Add an anniversary diary entry for the selected date
     (`diary-insert-anniversary-entry').

`i b'
     Add a block diary entry for the current region
     (`diary-insert-block-entry').

`i c'
     Add a cyclic diary entry starting at the date
     (`diary-insert-cyclic-entry').

   If you want to make a diary entry that applies to the anniversary of
a specific date, move point to that date and use the `i a' command.
This displays the end of your diary file in another window and inserts
the anniversary description; you can then type the rest of the diary
entry.  The entry looks like this:

     %%(diary-anniversary 10 31 1948) Arthur's birthday

This entry applies to October 31 in any year after 1948; `10 31 1948'
specifies the date.  (If you are using the European or ISO calendar
style, the input order of month, day and year is different.)  The
reason this expression requires a beginning year is that advanced diary
functions can use it to calculate the number of elapsed years.

   A "block" diary entry applies to a specified range of consecutive
dates.  Here is a block diary entry that applies to all dates from June
24, 2012 through July 10, 2012:

     %%(diary-block 6 24 2012 7 10 2012) Vacation

The `6 24 2012' indicates the starting date and the `7 10 2012'
indicates the stopping date.  (Again, if you are using the European or
ISO calendar style, the input order of month, day and year is
different.)

   To insert a block entry, place point and the mark on the two dates
that begin and end the range, and type `i b'.  This command displays
the end of your diary file in another window and inserts the block
description; you can then type the diary entry.

   "Cyclic" diary entries repeat after a fixed interval of days.  To
create one, select the starting date and use the `i c' command.  The
command prompts for the length of interval, then inserts the entry,
which looks like this:

     %%(diary-cyclic 50 3 1 2012) Renew medication

This entry applies to March 1, 2012 and every 50th day following; `3 1
2012' specifies the starting date.  (If you are using the European or
ISO calendar style, the input order of month, day and year is
different.)

   All three of these commands make marking diary entries.  To insert a
nonmarking entry, give a prefix argument to the command.  For example,
`C-u i a' makes a nonmarking anniversary diary entry.

   Marking sexp diary entries in the calendar can be time-consuming,
since every date visible in the calendar window must be individually
checked.  So it's a good idea to make sexp diary entries nonmarking
(with `&') when possible.

   Another sophisticated kind of sexp entry, a "floating" diary entry,
specifies a regularly occurring event by offsets specified in days,
weeks, and months.  It is comparable to a crontab entry interpreted by
the `cron' utility.  Here is a nonmarking, floating diary entry that
applies to the fourth Thursday in November:

     &%%(diary-float 11 4 4) American Thanksgiving

The 11 specifies November (the eleventh month), the 4 specifies Thursday
(the fourth day of the week, where Sunday is numbered zero), and the
second 4 specifies the fourth Thursday (1 would mean "first", 2 would
mean "second", -2 would mean "second-to-last", and so on).  The month
can be a single month or a list of months.  Thus you could change the
11 above to `'(1 2 3)' and have the entry apply to the last Thursday of
January, February, and March.  If the month is `t', the entry applies
to all months of the year.

   Each of the standard sexp diary entries takes an optional parameter
specifying the name of a face or a single-character string to use when
marking the entry in the calendar.  Most generally, sexp diary entries
can perform arbitrary computations to determine when they apply.  *Note
Sexp Diary Entries::.


File: emacs,  Node: Appointments,  Next: Importing Diary,  Prev: Diary,  Up: Calendar/Diary

31.11 Appointments
==================

If you have a diary entry for an appointment, and that diary entry
begins with a recognizable time of day, Emacs can warn you in advance
that an appointment is pending.  Emacs alerts you to the appointment by
displaying a message in your chosen format, as specified by the
variable `appt-display-format'.  If the value of `appt-audible' is
non-`nil', the warning includes an audible reminder.  In addition, if
`appt-display-mode-line' is non-`nil', Emacs displays the number of
minutes to the appointment on the mode line.

   If `appt-display-format' has the value `window', then the variable
`appt-display-duration' controls how long the reminder window is
visible for; and the variables `appt-disp-window-function' and
`appt-delete-window-function' give the names of functions used to
create and destroy the window, respectively.

   To enable appointment notification, type `M-x appt-activate'.  With
a positive argument, it enables notification; with a negative argument,
it disables notification; with no argument, it toggles.  Enabling
notification also sets up an appointment list for today from the diary
file, giving all diary entries found with recognizable times of day,
and reminds you just before each of them.

   For example, suppose the diary file contains these lines:

     Monday
       9:30am Coffee break
      12:00pm Lunch

Then on Mondays, you will be reminded at around 9:20am about your
coffee break and at around 11:50am about lunch.  The variable
`appt-message-warning-time' specifies how many minutes (default 12) in
advance to warn you.  This is a default warning time.  Each appointment
can specify a different warning time by adding a piece matching
`appt-warning-time-regexp' (see that variable's documentation for
details).

   You can write times in am/pm style (with `12:00am' standing for
midnight and `12:00pm' standing for noon), or 24-hour European/military
style.  You need not be consistent; your diary file can have a mixture
of the two styles.  Times must be at the beginning of diary entries if
they are to be recognized.

   Emacs updates the appointments list from the diary file
automatically just after midnight.  You can force an update at any time
by re-enabling appointment notification.  Both these actions also
display the day's diary buffer, unless you set `appt-display-diary' to
`nil'.  The appointments list is also updated whenever the diary file
(or a file it includes; see *note Fancy Diary Display::) is saved.

   You can also use the appointment notification facility like an alarm
clock.  The command `M-x appt-add' adds entries to the appointment list
without affecting your diary file.  You delete entries from the
appointment list with `M-x appt-delete'.


File: emacs,  Node: Importing Diary,  Next: Daylight Saving,  Prev: Appointments,  Up: Calendar/Diary

31.12 Importing and Exporting Diary Entries
===========================================

You can transfer diary entries between Emacs diary files and a variety
of other formats.

   You can import diary entries from Outlook-generated appointment
messages.  While viewing such a message in Rmail or Gnus, do `M-x
diary-from-outlook' to import the entry.  You can make this command
recognize additional appointment message formats by customizing the
variable `diary-outlook-formats'.

   The icalendar package allows you to transfer data between your Emacs
diary file and iCalendar files, which are defined in "RFC
2445--Internet Calendaring and Scheduling Core Object Specification
(iCalendar)" (as well as the earlier vCalendar format).

   The command `icalendar-import-buffer' extracts iCalendar data from
the current buffer and adds it to your diary file.  This function is
also suitable for automatic extraction of iCalendar data; for example
with the Rmail mail client one could use:

     (add-hook 'rmail-show-message-hook 'icalendar-import-buffer)

   The command `icalendar-import-file' imports an iCalendar file and
adds the results to an Emacs diary file.  For example:

     (icalendar-import-file "/here/is/calendar.ics"
                            "/there/goes/ical-diary")

You can use an `#include' directive to add the import file contents to
the main diary file, if these are different files.  *Note Fancy Diary
Display::.

   Use `icalendar-export-file' to interactively export an entire Emacs
diary file to iCalendar format.  To export only a part of a diary file,
mark the relevant area, and call `icalendar-export-region'.  In both
cases, Emacs appends the result to the target file.


File: emacs,  Node: Daylight Saving,  Next: Time Intervals,  Prev: Importing Diary,  Up: Calendar/Diary

31.13 Daylight Saving Time
==========================

Emacs understands the difference between standard time and daylight
saving time--the times given for sunrise, sunset, solstices, equinoxes,
and the phases of the moon take that into account.  The rules for
daylight saving time vary from place to place and have also varied
historically from year to year.  To do the job properly, Emacs needs to
know which rules to use.

   Some operating systems keep track of the rules that apply to the
place where you are; on these systems, Emacs gets the information it
needs from the system automatically.  If some or all of this
information is missing, Emacs fills in the gaps with the rules
currently used in Cambridge, Massachusetts.  If the resulting rules are
not what you want, you can tell Emacs the rules to use by setting
certain variables: `calendar-daylight-savings-starts' and
`calendar-daylight-savings-ends'.

   These values should be Lisp expressions that refer to the variable
`year', and evaluate to the Gregorian date on which daylight saving
time starts or (respectively) ends, in the form of a list `(MONTH DAY
YEAR)'.  The values should be `nil' if your area does not use daylight
saving time.

   Emacs uses these expressions to determine the starting date of
daylight saving time for the holiday list and for correcting times of
day in the solar and lunar calculations.

   The values for Cambridge, Massachusetts are as follows:

     (calendar-nth-named-day 2 0 3 year)
     (calendar-nth-named-day 1 0 11 year)

That is, the second 0th day (Sunday) of the third month (March) in the
year specified by `year', and the first Sunday of the eleventh month
(November) of that year.  If daylight saving time were changed to start
on October 1, you would set `calendar-daylight-savings-starts' to this:

     (list 10 1 year)

   If there is no daylight saving time at your location, or if you want
all times in standard time, set `calendar-daylight-savings-starts' and
`calendar-daylight-savings-ends' to `nil'.

   The variable `calendar-daylight-time-offset' specifies the
difference between daylight saving time and standard time, measured in
minutes.  The value for Cambridge, Massachusetts is 60.

   Finally, the two variables `calendar-daylight-savings-starts-time'
and `calendar-daylight-savings-ends-time' specify the number of minutes
after midnight local time when the transition to and from daylight
saving time should occur.  For Cambridge, Massachusetts both variables'
values are 120.


File: emacs,  Node: Time Intervals,  Next: Advanced Calendar/Diary Usage,  Prev: Daylight Saving,  Up: Calendar/Diary

31.14 Summing Time Intervals
============================

The timeclock package adds up time intervals, so you can (for instance)
keep track of how much time you spend working on particular projects.

   Use the `M-x timeclock-in' command when you start working on a
project, and `M-x timeclock-out' command when you're done.  Each time
you do this, it adds one time interval to the record of the project.
You can change to working on a different project with `M-x
timeclock-change'.

   Once you've collected data from a number of time intervals, you can
use `M-x timeclock-workday-remaining' to see how much time is left to
work today (assuming a typical average of 8 hours a day), and `M-x
timeclock-when-to-leave' which will calculate when you're "done".

   If you want Emacs to display the amount of time "left" of your
workday in the mode line, either customize the
`timeclock-modeline-display' variable and set its value to `t', or
invoke the `M-x timeclock-modeline-display' command.

   Terminating the current Emacs session might or might not mean that
you have stopped working on the project and, by default, Emacs asks
you.  You can, however, customize the value of the variable
`timeclock-ask-before-exiting' to `nil' to avoid the question; then,
only an explicit `M-x timeclock-out' or `M-x timeclock-change' will
tell Emacs that the current interval is over.

   The timeclock functions work by accumulating the data in a file
called `.timelog' in your home directory.  You can specify a different
name for this file by customizing the variable `timeclock-file'.  If
you edit the timeclock file manually, or if you change the value of any
of timeclock's customizable variables, you should run the command `M-x
timeclock-reread-log' to update the data in Emacs from the file.


File: emacs,  Node: Advanced Calendar/Diary Usage,  Prev: Time Intervals,  Up: Calendar/Diary

31.15 Customizing the Calendar and Diary
========================================

There are many ways in which you can customize the calendar and diary
to suit your personal tastes.

* Menu:

* Calendar Customizing::   Calendar layout and hooks.
* Holiday Customizing::    Defining your own holidays.
* Date Display Format::    Changing the format.
* Time Display Format::    Changing the format.
* Diary Customizing::      Defaults you can set.
* Non-Gregorian Diary::    Diary entries based on other calendars.
* Diary Display::          A choice of ways to display the diary.
* Fancy Diary Display::    Sorting diary entries, using included diary files.
* Sexp Diary Entries::     More flexible diary entries.


File: emacs,  Node: Calendar Customizing,  Next: Holiday Customizing,  Up: Advanced Calendar/Diary Usage

31.15.1 Customizing the Calendar
--------------------------------

The calendar display unfortunately cannot be changed from three months,
but you can customize the whitespace used by setting the variables:
`calendar-left-margin', `calendar-day-header-width',
`calendar-day-digit-width', `calendar-column-width', and
`calendar-intermonth-spacing'.  To display text _between_ the months,
for example week numbers, customize the variables
`calendar-intermonth-header' and `calendar-intermonth-text' as
described in their documentation.

   The variable `calendar-holiday-marker' specifies how to mark a date
that is a holiday.  Its value may be a single-character string to
insert next to the date, or a face name to use for displaying the date.
Likewise, the variable `diary-entry-marker' specifies how to mark a
date that has diary entries.  The function `calendar-mark-today' uses
`calendar-today-marker' to mark today's date.  By default, the calendar
uses faces named `holiday', `diary', and `calendar-today' for these
purposes.

   The variable `calendar-load-hook' is a normal hook run when the
calendar package is first loaded (before actually starting to display
the calendar).

   Starting the calendar runs the normal hook
`calendar-initial-window-hook'.  Recomputation of the calendar display
does not run this hook.  But if you leave the calendar with the `q'
command and reenter it, the hook runs again.

   The variable `calendar-today-visible-hook' is a normal hook run
after the calendar buffer has been prepared with the calendar, when the
current date is visible in the window.  One use of this hook is to mark
today's date; to do that use either of the functions
`calendar-mark-today' or `calendar-star-date':

     (add-hook 'calendar-today-visible-hook 'calendar-mark-today)

A similar normal hook, `calendar-today-invisible-hook' is run if the
current date is _not_ visible in the window.

   Each of the calendar cursor motion commands runs the hook
`calendar-move-hook' after it moves the cursor.


File: emacs,  Node: Holiday Customizing,  Next: Date Display Format,  Prev: Calendar Customizing,  Up: Advanced Calendar/Diary Usage

31.15.2 Customizing the Holidays
--------------------------------

There are several variables listing the default holidays that Emacs
knows about.  These are: `holiday-general-holidays',
`holiday-local-holidays', `holiday-solar-holidays',
`holiday-bahai-holidays', `holiday-christian-holidays',
`holiday-hebrew-holidays', `holiday-islamic-holidays',
`holiday-oriental-holidays', and `holiday-other-holidays'.  The names
should be self-explanatory; e.g. `holiday-solar-holidays' lists sun-
and moon-related holidays.

   You can customize these lists of holidays to your own needs,
deleting or adding holidays as described below.  Set any of them to
`nil' to not show the associated holidays.

   The general holidays are, by default, holidays common throughout the
United States.  In contrast, `holiday-local-holidays' and
`holiday-other-holidays' are both empty by default.  These are intended
for system-wide settings and your individual use, respectively.

   By default, Emacs does not include all the holidays of the religions
that it knows, only those commonly found in secular calendars.  For a
more extensive collection of religious holidays, you can set any (or
all) of the variables `calendar-bahai-all-holidays-flag',
`calendar-christian-all-holidays-flag',
`calendar-hebrew-all-holidays-flag', or
`calendar-islamic-all-holidays-flag' to `t'.

   Each of the holiday variables is a list of "holiday forms", each
form describing a holiday (or sometimes a list of holidays).  Here is a
table of the possible kinds of holiday form.  Day numbers and month
numbers count starting from 1, but "dayname" numbers count Sunday as 0.
The argument STRING is always the description of the holiday, as a
string.

`(holiday-fixed MONTH DAY STRING)'
     A fixed date on the Gregorian calendar.

`(holiday-float MONTH DAYNAME K STRING'
     &optional DAY) The Kth DAYNAME (DAYNAME=0 for Sunday, and so on)
     after or before Gregorian date MONTH, DAY.  Negative K means count
     back from the end of the month.  Optional DAY defaults to 1 if K
     is positive, and the last day of MONTH otherwise.

`(holiday-chinese MONTH DAY STRING)'
     A fixed date on the Chinese calendar.

`(holiday-hebrew MONTH DAY STRING)'
     A fixed date on the Hebrew calendar.

`(holiday-islamic MONTH DAY STRING)'
     A fixed date on the Islamic calendar.

`(holiday-julian MONTH DAY STRING)'
     A fixed date on the Julian calendar.

`(holiday-sexp SEXP STRING)'
     A date calculated by the Lisp expression SEXP.  The expression
     should use the variable `year' to compute and return the date of a
     holiday in the form of a list `(MONTH DAY YEAR)', or `nil' if the
     holiday doesn't happen this year.

`(if CONDITION HOLIDAY-FORM)'
     A holiday that happens only if CONDITION is true.

`(FUNCTION [ARGS])'
     A list of dates calculated by the function FUNCTION, called with
     arguments ARGS.

   For example, suppose you want to add Bastille Day, celebrated in
France on July 14 (i.e., the fourteenth day of the seventh month).  You
can do this as follows:

     (setq holiday-other-holidays '((holiday-fixed 7 14 "Bastille Day")))

   Many holidays occur on a specific day of the week, at a specific time
of month.  Here is a holiday form describing Hurricane Supplication Day,
celebrated in the Virgin Islands on the fourth Monday in August:

     (holiday-float 8 1 4 "Hurricane Supplication Day")

Here the 8 specifies August, the 1 specifies Monday (Sunday is 0,
Tuesday is 2, and so on), and the 4 specifies the fourth occurrence in
the month (1 specifies the first occurrence, 2 the second occurrence,
-1 the last occurrence, -2 the second-to-last occurrence, and so on).

   You can specify holidays that occur on fixed days of the Bah�'�,
Chinese, Hebrew, Islamic, and Julian calendars too.  For example,

     (setq holiday-other-holidays
           '((holiday-hebrew 10 2 "Last day of Hanukkah")
             (holiday-islamic 3 12 "Mohammed's Birthday")
             (holiday-julian 4 2 "Jefferson's Birthday")))

adds the last day of Hanukkah (since the Hebrew months are numbered with
1 starting from Nisan), the Islamic feast celebrating Mohammed's
birthday (since the Islamic months are numbered from 1 starting with
Muharram), and Thomas Jefferson's birthday, which is 2 April 1743 on the
Julian calendar.

   To include a holiday conditionally, use either Emacs Lisp's `if' or
the `holiday-sexp' form.  For example, American presidential elections
occur on the first Tuesday after the first Monday in November of years
divisible by 4:

     (holiday-sexp '(if (zerop (% year 4))
                        (calendar-gregorian-from-absolute
                         (1+ (calendar-dayname-on-or-before
                               1 (+ 6 (calendar-absolute-from-gregorian
                                       (list 11 1 year)))))))
                   "US Presidential Election")

or

     (if (zerop (% displayed-year 4))
         (holiday-fixed 11
                (calendar-extract-day
                  (calendar-gregorian-from-absolute
                    (1+ (calendar-dayname-on-or-before
                          1 (+ 6 (calendar-absolute-from-gregorian
                                   (list 11 1 displayed-year)))))))
                "US Presidential Election"))

   Some holidays just don't fit into any of these forms because special
calculations are involved in their determination.  In such cases you
must write a Lisp function to do the calculation.  To include eclipses,
for example, add `(eclipses)' to `holiday-other-holidays' and write an
Emacs Lisp function `eclipses' that returns a (possibly empty) list of
the relevant Gregorian dates among the range visible in the calendar
window, with descriptive strings, like this:

     (((6 4 2012) "Lunar Eclipse") ((11 13 2012) "Solar Eclipse") ... )


File: emacs,  Node: Date Display Format,  Next: Time Display Format,  Prev: Holiday Customizing,  Up: Advanced Calendar/Diary Usage

31.15.3 Date Display Format
---------------------------

You can customize the way dates are displayed in the diary, mode lines,
and messages by setting `calendar-date-display-form'.  This variable
holds a list of expressions that can involve the variables `month',
`day', and `year', which are all numbers in string form, and
`monthname' and `dayname', which are both alphabetic strings.  In the
American style, the default value of this list is as follows:

     ((if dayname (concat dayname ", ")) monthname " " day ", " year)

while in the European style this value is the default:

     ((if dayname (concat dayname ", ")) day " " monthname " " year)

The default ISO date representation is:

     ((format "%s-%.2d-%.2d" year (string-to-number month)
              (string-to-number day)))

Another typical American format is:

     (month "/" day "/" (substring year -2))


File: emacs,  Node: Time Display Format,  Next: Diary Customizing,  Prev: Date Display Format,  Up: Advanced Calendar/Diary Usage

31.15.4 Time Display Format
---------------------------

The calendar and diary by default display times of day in the
conventional American style with the hours from 1 through 12, minutes,
and either `am' or `pm'.  If you prefer the European style, also known
in the US as military, in which the hours go from 00 to 23, you can
alter the variable `calendar-time-display-form'.  This variable is a
list of expressions that can involve the variables `12-hours',
`24-hours', and `minutes', which are all numbers in string form, and
`am-pm' and `time-zone', which are both alphabetic strings.  The
default value is:

     (12-hours ":" minutes am-pm
               (if time-zone " (") time-zone (if time-zone ")"))

Here is a value that provides European style times:

     (24-hours ":" minutes
               (if time-zone " (") time-zone (if time-zone ")"))

   Note that few calendar functions return a time of day (at present,
only solar functions).


File: emacs,  Node: Diary Customizing,  Next: Non-Gregorian Diary,  Prev: Time Display Format,  Up: Advanced Calendar/Diary Usage

31.15.5 Customizing the Diary
-----------------------------

Ordinarily, the diary window indicates any holidays that fall on the
date of the diary entries, either in the mode line or the buffer itself.
The process of checking for holidays can be slow, depending on the
defined holidays.  In that case, setting `diary-show-holidays-flag' to
`nil' will speed up the diary display.

   The variable `diary-number-of-entries' controls the number of days
of diary entries to be displayed at one time.  It affects the initial
display when `calendar-view-diary-initially-flag' is `t', as well as
the command `M-x diary'.  For example, a value of 1 (the default)
displays only the current day's diary entries, whereas a value of 2
will also show the next day's entries.  The value can also be a vector
of seven integers: for example, if the value is `[0 2 2 2 2 4 1]' then
no diary entries appear on Sunday, the current date's and the next
day's diary entries appear Monday through Thursday, Friday through
Monday's entries appear on Friday, while on Saturday only that day's
entries appear.

   You can customize the form of dates in your diary file by setting the
variable `diary-date-forms'.  This variable is a list of patterns for
recognizing a date.  Each date pattern is a list whose elements may be
regular expressions (*note Regular Expressions: (elisp)Regular
Expressions.) or the symbols `month', `day', `year', `monthname', and
`dayname'.  All these elements serve as patterns that match certain
kinds of text in the diary file.  In order for the date pattern as a
whole to match, all of its elements must match consecutively.

   A regular expression in a date pattern matches in its usual fashion,
using the standard syntax table altered so that `*' is a word
constituent.

   The symbols `month', `day', `year', `monthname', and `dayname' match
the month number, day number, year number, month name, and day name of
the date being considered.  The symbols that match numbers allow
leading zeros; those that match names allow capitalization and
abbreviation (as specified by `calendar-month-abbrev-array' and
`calendar-day-abbrev-array').  All the symbols can match `*'; since `*'
in a diary entry means "any day", "any month", and so on, it should
match regardless of the date being considered.

   The default value of `diary-date-forms' in the American style is
provided by `diary-american-date-forms':

     ((month "/" day "[^/0-9]")
      (month "/" day "/" year "[^0-9]")
      (monthname " *" day "[^,0-9]")
      (monthname " *" day ", *" year "[^0-9]")
      (dayname "\\W"))

The variables `diary-european-date-forms' and `diary-iso-date-forms'
provide other default styles.

   The date patterns in the list must be _mutually exclusive_ and must
not match any portion of the diary entry itself, just the date and one
character of whitespace.  If, to be mutually exclusive, the pattern
must match a portion of the diary entry text--beyond the whitespace
that ends the date--then the first element of the date pattern _must_
be `backup'.  This causes the date recognizer to back up to the
beginning of the current word of the diary entry, after finishing the
match.  Even if you use `backup', the date pattern must absolutely not
match more than a portion of the first word of the diary entry.  For
example, the default value of `diary-european-date-forms' is:

     ((day "/" month "[^/0-9]")
      (day "/" month "/" year "[^0-9]")
      (backup day " *" monthname "\\W+\\<\\([^*0-9]\\|\\([0-9]+[:aApP]\\)\\)")
      (day " *" monthname " *" year "[^0-9]")
      (dayname "\\W"))

Notice the use of `backup' in the third pattern, because it needs to
match part of a word beyond the date itself to distinguish it from the
fourth pattern.


File: emacs,  Node: Non-Gregorian Diary,  Next: Diary Display,  Prev: Diary Customizing,  Up: Advanced Calendar/Diary Usage

31.15.6 Diary Entries Using non-Gregorian Calendars
---------------------------------------------------

As well as entries based on the standard Gregorian calendar, your diary
can have entries based on Bah�'�, Hebrew, or Islamic dates.
Recognition of such entries can be time-consuming, however, and since
most people don't use them, you must explicitly enable their use.  If
you want the diary to recognize Hebrew-date diary entries, for example,
you must do this:

     (add-hook 'diary-nongregorian-listing-hook 'diary-hebrew-list-entries)
     (add-hook 'diary-nongregorian-marking-hook 'diary-hebrew-mark-entries)

Similarly, for Islamic and Bah�'� entries, add
`diary-islamic-list-entries' and `diary-islamic-mark-entries', or
`diary-bahai-list-entries' and `diary-bahai-mark-entries'.

   These diary entries have the same formats as Gregorian-date diary
entries; except that `diary-bahai-entry-symbol' (default `B') must
precede a Bah�'� date, `diary-hebrew-entry-symbol' (default `H') a
Hebrew date, and `diary-islamic-entry-symbol' (default `I') an Islamic
date.  Moreover, non-Gregorian month names may not be abbreviated
(because the first three letters are often not unique).  (Note also
that you must use "Adar I" if you want Adar of a common Hebrew year.)
For example, a diary entry for the Hebrew date Heshvan 25 could look
like this:

     HHeshvan 25 Happy Hebrew birthday!

and would appear in the diary for any date that corresponds to Heshvan
25 on the Hebrew calendar.  And here is an Islamic-date diary entry
that matches Dhu al-Qada 25:

     IDhu al-Qada 25 Happy Islamic birthday!

   As with Gregorian-date diary entries, non-Gregorian entries are
nonmarking if preceded by `diary-nonmarking-symbol' (default `&').

   Here is a table of commands used in the calendar to create diary
entries that match the selected date and other dates that are similar in
the Bah�'�, Hebrew, or Islamic calendars:

`i h d'
     `diary-hebrew-insert-entry'

`i h m'
     `diary-hebrew-insert-monthly-entry'

`i h y'
     `diary-hebrew-insert-yearly-entry'

`i i d'
     `diary-islamic-insert-entry'

`i i m'
     `diary-islamic-insert-monthly-entry'

`i i y'
     `diary-islamic-insert-yearly-entry'

`i B d'
     `diary-bahai-insert-entry'

`i B m'
     `diary-bahai-insert-monthly-entry'

`i B y'
     `diary-bahai-insert-yearly-entry'

   These commands work much like the corresponding commands for ordinary
diary entries: they apply to the date that point is on in the calendar
window, and what they do is insert just the date portion of a diary
entry at the end of your diary file.  You must then insert the rest of
the diary entry.  The basic commands add an entry for the specific
non-Gregorian date, the `monthly' commands for the given non-Gregorian
day-within-month in every month, and the `yearly' commands for the
given non-Gregorian day and month in every year.


File: emacs,  Node: Diary Display,  Next: Fancy Diary Display,  Prev: Non-Gregorian Diary,  Up: Advanced Calendar/Diary Usage

31.15.7 Diary Display
---------------------

Diary display works by preparing the list of diary entries and then
running the function specified by the variable
`diary-display-function'.  The default value `diary-fancy-display'
displays diary entries and holidays by copying them into a special
buffer that exists only for the sake of display.  Copying diary entries
to a separate buffer provides an opportunity to change the displayed
text to make it prettier--for example, to sort the entries by the dates
they apply to.

   Ordinarily, the fancy diary buffer does not show days for which there
are no diary entries, even if that day is a holiday.  If you want such
days to be shown in the fancy diary buffer, set the variable
`diary-list-include-blanks' to `t'.

   The fancy diary buffer enables View mode (*note View Mode::).

   The alternative display method `diary-simple-display' shows the
actual diary buffer, and uses invisible text to hide entries that don't
apply.  Holidays are shown in the mode line.  The advantage of this
method is that you can edit the buffer and save your changes directly to
the diary file.  This method is not as flexible as the fancy method,
however.  For example, it cannot sort entries.  Another disadvantage is
that invisible text can be confusing.  For example, if you copy a region
of text in order to paste it elsewhere, invisible text may be included.
Similarly, since the diary buffer as you see it is an illusion, simply
printing the buffer may not print what you see on your screen.

   For this reason, there is a special command to print hard copy of the
diary buffer _as it appears_; this command is `M-x
diary-print-entries'.  It works with either display method, although
with the fancy display you can also print the buffer like any other.  To
print a hard copy of a day-by-day diary for a week, position point on
the first day of the week, type `7 d', and then do `M-x
diary-print-entries'.  As usual, the inclusion of the holidays slows
down the display slightly; you can speed things up by setting the
variable `diary-show-holidays-flag' to `nil'.

   This command prepares a temporary buffer that contains only the diary
entries currently visible in the diary buffer.  Unlike with the simple
display, the other irrelevant entries are really absent, not just
hidden.  After preparing the buffer, it runs the hook
`diary-print-entries-hook'.  The default value of this hook sends the
data directly to the printer with the command `lpr-buffer' (*note
Printing::).  If you want to use a different command to do the
printing, just change the value of this hook.  Other uses might include,
for example, rearranging the lines into order by day and time.

   You can edit the diary entries as they appear in the simple diary
window, but it is important to remember that the buffer displayed
contains the _entire_ diary file, with portions of it concealed from
view.  This means, for instance, that the `C-f' (`forward-char')
command can put point at what appears to be the end of the line, but
what is in reality the middle of some concealed line.

   _Be careful when editing the diary entries in the simple display!_
Inserting additional lines or adding/deleting characters in the middle
of a visible line cannot cause problems, but editing at the end of a
line may not do what you expect.  Deleting a line may delete other
invisible entries that follow it.  Before editing the simple diary
buffer, it is best to display the entire file with `s'
(`diary-show-all-entries').


File: emacs,  Node: Fancy Diary Display,  Next: Sexp Diary Entries,  Prev: Diary Display,  Up: Advanced Calendar/Diary Usage

31.15.8 Fancy Diary Display
---------------------------

The following features only work with the fancy diary display.

   You can use the normal hook `diary-list-entries-hook' to sort each
day's diary entries by their time of day.  Here's how:

     (add-hook 'diary-list-entries-hook 'diary-sort-entries t)

For each day, this sorts diary entries that begin with a recognizable
time of day according to their times.  Diary entries without times come
first within each day.  Note how the sort command is placed at the end
of the hook list, in case earlier members of the list change the order
of the diary entries, or add items.

   You can write `comments' in diary entries, by setting the variables
`diary-comment-start' and `diary-comment-end' to strings that delimit
comments.  The fancy display does not print comments.  You might want
to put meta-data for the use of other packages (e.g. the appointment
package, *note Appointments::) inside comments.

   Your main diary file can include other files.  This permits a group
of people to share a diary file for events that apply to all of them.
Lines in the diary file starting with `diary-include-string':

     #include "FILENAME"

include the diary entries from the file FILENAME in the fancy diary
buffer.  The include mechanism is recursive, so that included files can
include other files, and so on (you must be careful not to have a cycle
of inclusions, of course).  Here is how to enable the include facility:

     (add-hook 'diary-list-entries-hook 'diary-include-other-diary-files)
     (add-hook 'diary-mark-entries-hook 'diary-mark-included-diary-files)

   The include mechanism works only with the fancy diary display,
because simple diary display shows the entries directly from your diary
file.



Local Variables:
coding: iso-8859-1
End:
